ja4plus 0.2.0__py3-none-any.whl

ja4plus/fingerprinters/ja4h.py

@@ -0,0 +1,131 @@
+"""
+JA4H HTTP Request Fingerprinting implementation.
+
+JA4H fingerprints HTTP requests based on:
+1. HTTP method, version, cookie flag, referer flag, header count, and language
+2. Headers hash in the order they appear
+3. Sorted cookie field names hash
+4. Sorted cookie fields + values hash
+"""
+
+import hashlib
+from scapy.all import IP, TCP, Raw
+from ja4plus.utils.http_utils import extract_http_info
+from ja4plus.fingerprinters.base import BaseFingerprinter
+
+
+class JA4HFingerprinter(BaseFingerprinter):
+    """
+    JA4H HTTP Fingerprinting implementation.
+
+    JA4H fingerprints HTTP requests based on method, headers, and cookies.
+    """
+
+    def process_packet(self, packet):
+        """
+        Process a packet and extract JA4H fingerprint if applicable.
+
+        Args:
+            packet: A network packet to analyze
+
+        Returns:
+            The extracted fingerprint if successful, None otherwise
+        """
+        fingerprint = generate_ja4h(packet)
+        if fingerprint:
+            self.add_fingerprint(fingerprint, packet)
+            return fingerprint
+        return None
+
+
+def generate_ja4h(packet):
+    """
+    Generate JA4H fingerprint from HTTP request.
+
+    Args:
+        packet: An HTTP request packet
+
+    Returns:
+        JA4H fingerprint string if successful, None otherwise
+    """
+    # Extract HTTP info
+    http_info = extract_http_info(packet)
+    if not http_info:
+        return None
+
+    try:
+        # Part A: HTTP method, version, cookies, referer, header count, language
+        method = http_info.get('method', '').lower()
+        version = http_info.get('version', '').replace('HTTP/', '')
+
+        # Format version (e.g., "1.1" to "11", "2.0" to "20")
+        version_str = version.replace('.', '')
+
+        # Cookie indicator
+        has_cookie = 'c' if http_info.get('cookie_fields', []) else 'n'
+
+        # Referer indicator
+        has_referer = 'r' if http_info.get('referer', '') else 'n'
+
+        # Count of headers (excluding Cookie and Referer) - 2 digit format
+        header_count = 0
+        for header in http_info.get('headers', []):
+            if header.lower() not in ['cookie', 'referer']:
+                header_count += 1
+        header_count = min(header_count, 99)
+        header_count_str = f"{header_count:02d}"
+
+        # Extract language code per FoxIO spec:
+        # Replace hyphens, replace semicolons with commas, lowercase, take first,
+        # truncate to 4 chars, pad with zeros to 4 chars
+        language = http_info.get('language', '')
+        lang_code = '0000'
+        if language:
+            lang_clean = language.replace('-', '').replace(';', ',').lower().split(',')[0]
+            lang_clean = lang_clean[:4]
+            lang_code = f"{lang_clean}{'0' * (4 - len(lang_clean))}" if lang_clean else '0000'
+
+        part_a = f"{method[:2]}{version_str}{has_cookie}{has_referer}{header_count_str}{lang_code}"
+
+        # Part B: Header names hash - keep original order
+        # Per FoxIO spec: exclude pseudo-headers (starting with ':'),
+        # Cookie, Referer, and empty headers from the hash
+        headers = http_info.get('headers', [])
+        filtered_headers = [
+            h for h in headers
+            if not h.startswith(':')
+            and h.lower() != 'cookie'
+            and h.lower() != 'referer'
+            and h
+        ]
+        headers_str = ','.join(filtered_headers)
+        if headers_str:
+            part_b = hashlib.sha256(headers_str.encode()).hexdigest()[:12]
+        else:
+            part_b = '000000000000'
+
+        # Part C: Cookie field names hash (sorted alphabetically)
+        cookie_fields = sorted(http_info.get('cookie_fields', []))
+        cookie_fields_str = ','.join(cookie_fields)
+        if cookie_fields_str:
+            part_c = hashlib.sha256(cookie_fields_str.encode()).hexdigest()[:12]
+        else:
+            part_c = '000000000000'
+
+        # Part D: Cookie values hash - per FoxIO spec, hash the full
+        # "name=value" cookie strings sorted alphabetically by name
+        cookie_dict = http_info.get('cookies', {})
+        sorted_cookie_pairs = sorted(cookie_dict.items())
+        cookie_values_str = ','.join(f"{k}={v}" for k, v in sorted_cookie_pairs)
+        if cookie_values_str:
+            part_d = hashlib.sha256(cookie_values_str.encode()).hexdigest()[:12]
+        else:
+            part_d = '000000000000'
+
+        # Form the JA4H fingerprint
+        ja4h = f"{part_a}_{part_b}_{part_c}_{part_d}"
+
+        return ja4h
+
+    except Exception:
+        return None

ja4plus/fingerprinters/ja4l.py

@@ -0,0 +1,265 @@
+"""
+JA4L Light Distance/Location Fingerprinting implementation.
+
+JA4L measures the latency between client and server by analyzing
+TCP handshake timing, allowing for physical distance estimation.
+Format: JA4L-C=<latency_us>_<ttl> and JA4L-S=<latency_us>_<ttl>
+"""
+
+import time
+from scapy.all import IP, TCP, UDP
+from ja4plus.fingerprinters.base import BaseFingerprinter
+
+
+class JA4LFingerprinter(BaseFingerprinter):
+    """
+    JA4L Light Distance/Location Fingerprinting implementation.
+
+    JA4L measures latency between client and server to estimate physical distance.
+    """
+
+    def __init__(self):
+        """Initialize the fingerprinter."""
+        super().__init__()
+        self.connections = {}
+
+    def process_packet(self, packet):
+        """
+        Process a packet and extract JA4L fingerprint if applicable.
+
+        Args:
+            packet: A network packet to analyze
+
+        Returns:
+            The extracted fingerprint if successful, None otherwise
+        """
+        if IP not in packet or (TCP not in packet and UDP not in packet):
+            return None
+
+        if TCP in packet:
+            proto = 'tcp'
+            sport = packet[TCP].sport
+            dport = packet[TCP].dport
+        else:
+            proto = 'udp'
+            sport = packet[UDP].sport
+            dport = packet[UDP].dport
+
+        src_ip = packet[IP].src
+        dst_ip = packet[IP].dst
+
+        # Normalize connection key (ordered src/dst)
+        if src_ip < dst_ip or (src_ip == dst_ip and sport < dport):
+            conn_key = f"{proto}_{src_ip}:{sport}_{dst_ip}:{dport}"
+            direction = 'forward'
+        else:
+            conn_key = f"{proto}_{dst_ip}:{dport}_{src_ip}:{sport}"
+            direction = 'reverse'
+
+        if conn_key not in self.connections:
+            self.connections[conn_key] = {
+                'proto': proto,
+                'direction': direction,
+                'conn_key': conn_key,
+                'timestamps': {},
+                'ttls': {}
+            }
+
+        conn = self.connections[conn_key]
+        fingerprint = generate_ja4l(packet, conn)
+
+        if fingerprint:
+            self.fingerprints.append({
+                'fingerprint': fingerprint,
+                'packet': packet,
+                'connection': conn_key
+            })
+            return fingerprint
+
+        return None
+
+    def reset(self):
+        """Reset all fingerprints and connection tracking."""
+        super().reset()
+        self.connections = {}
+
+    def calculate_distance(self, latency_us, propagation_factor=1.6):
+        """
+        Calculate the physical distance based on JA4L latency.
+
+        Args:
+            latency_us: One-way latency in microseconds
+            propagation_factor: Propagation delay factor (default: 1.6)
+
+        Returns:
+            Distance in miles
+        """
+        # Speed of light per us in fiber (miles/us)
+        speed_of_light = 0.128
+        distance = (latency_us * speed_of_light) / propagation_factor
+        return distance
+
+    def calculate_distance_km(self, latency_us, propagation_factor=1.6):
+        """
+        Calculate the physical distance in kilometers.
+
+        Args:
+            latency_us: One-way latency in microseconds
+            propagation_factor: Propagation delay factor (default: 1.6)
+
+        Returns:
+            Distance in kilometers
+        """
+        speed_of_light_km = 0.206  # km/us in fiber
+        distance = (latency_us * speed_of_light_km) / propagation_factor
+        return distance
+
+    def estimate_os(self, ttl):
+        """
+        Estimate the operating system based on TTL value.
+
+        Args:
+            ttl: Observed TTL value
+
+        Returns:
+            String indicating likely OS or device type
+        """
+        if ttl <= 64:
+            return "Mac, Linux, Phone, or IoT device (initial TTL: 64)"
+        elif ttl <= 128:
+            return "Windows (initial TTL: 128)"
+        else:
+            return "Cisco, F5, or Networking Device (initial TTL: 255)"
+
+    def estimate_hop_count(self, ttl):
+        """
+        Estimate the hop count based on TTL value.
+
+        Args:
+            ttl: Observed TTL value
+
+        Returns:
+            Estimated hop count
+        """
+        if ttl <= 64:
+            return 64 - ttl
+        elif ttl <= 128:
+            return 128 - ttl
+        else:
+            return 255 - ttl
+
+
+def generate_ja4l(packet, conn=None):
+    """
+    Generate JA4L latency fingerprint based on packet timing.
+
+    Uses the TCP 3-way handshake or QUIC handshake to measure one-way latency.
+    Time is measured in microseconds.
+
+    Args:
+        packet: A network packet
+        conn: Connection tracking object with timestamps dict
+
+    Returns:
+        JA4L fingerprint string if successful, None otherwise
+    """
+    if not conn:
+        return None
+
+    if not packet.haslayer(IP):
+        return None
+
+    try:
+        if 'timestamps' not in conn:
+            conn['timestamps'] = {}
+        if 'ttls' not in conn:
+            conn['ttls'] = {}
+
+        ttl = packet[IP].ttl
+
+        # Use pcap timestamp if available (for offline analysis), else wall clock
+        current_time = float(packet.time) if hasattr(packet, 'time') else time.time()
+
+        # Handle TCP protocol
+        if packet.haslayer(TCP):
+            tcp_flags = packet[TCP].flags
+
+            # SYN packet (point A) - client initiates
+            if tcp_flags & 0x02 == 0x02 and not tcp_flags & 0x10:
+                conn['timestamps']['A'] = current_time
+                conn['ttls']['client'] = ttl
+                return None
+
+            # SYN-ACK packet (point B) - server responds
+            elif tcp_flags & 0x12 == 0x12:
+                conn['timestamps']['B'] = current_time
+                conn['ttls']['server'] = ttl
+
+                if 'A' in conn['timestamps']:
+                    # Per FoxIO spec: use raw time difference (not divided by 2)
+                    diff = conn['timestamps']['B'] - conn['timestamps']['A']
+                    latency = max(1, int(diff * 1000000))
+                    return f"JA4L-S={latency}_{ttl}"
+
+            # ACK packet (point C) - client completes handshake
+            elif tcp_flags & 0x10 == 0x10 and not tcp_flags & 0x02:
+                conn['timestamps']['C'] = current_time
+
+                if 'B' in conn['timestamps']:
+                    diff = conn['timestamps']['C'] - conn['timestamps']['B']
+                    latency = max(1, int(diff * 1000000))
+                    return f"JA4L-C={latency}_{ttl}"
+
+        # Handle QUIC (UDP) protocol
+        elif packet.haslayer(UDP) and conn.get('proto') == 'udp':
+            is_client = _src_is_client(packet, conn)
+
+            if 'A' not in conn['timestamps'] and is_client:
+                conn['timestamps']['A'] = current_time
+                conn['ttls']['client'] = ttl
+
+            elif 'A' in conn['timestamps'] and not is_client and 'B' not in conn['timestamps']:
+                conn['timestamps']['B'] = current_time
+                conn['ttls']['server'] = ttl
+                diff = conn['timestamps']['B'] - conn['timestamps']['A']
+                latency = max(1, int(diff * 1000000))
+                return f"JA4L-S={latency}_{ttl}"
+
+            elif 'B' in conn['timestamps'] and is_client and 'C' not in conn['timestamps']:
+                conn['timestamps']['C'] = current_time
+
+            elif 'C' in conn['timestamps'] and not is_client and 'D' not in conn['timestamps']:
+                conn['timestamps']['D'] = current_time
+                diff = conn['timestamps']['D'] - conn['timestamps']['C']
+                latency = max(1, int(diff * 1000000))
+                return f"JA4L-C={latency}_{conn['ttls'].get('client', ttl)}"
+
+        return None
+    except Exception:
+        return None
+
+
+def _src_is_client(packet, conn):
+    """
+    Determine if the source of the packet is the client side.
+
+    Args:
+        packet: The packet to analyze
+        conn: Connection tracking information
+
+    Returns:
+        True if the source is the client, False otherwise
+    """
+    if not packet.haslayer(IP):
+        return False
+
+    src_ip = packet[IP].src
+
+    if conn.get('direction') == 'forward':
+        conn_key = conn.get('conn_key', '')
+        parts = conn_key.split('_')
+        if len(parts) >= 2:
+            client_part = parts[1].split(':')[0]
+            return src_ip == client_part
+
+    return False

ja4plus/fingerprinters/ja4s.py

@@ -0,0 +1,144 @@
+"""
+JA4S TLS Server Hello Fingerprinting implementation.
+"""
+
+import hashlib
+from scapy.all import IP, TCP, Raw
+from ja4plus.utils.tls_utils import extract_tls_info, is_grease_value
+from ja4plus.fingerprinters.base import BaseFingerprinter
+
+
+class JA4SFingerprinter(BaseFingerprinter):
+    """
+    JA4S TLS Server Hello Fingerprinting implementation.
+
+    JA4S fingerprints server responses in TLS handshakes.
+    Format: <proto><version><ext_count><alpn>_<cipher>_<ext_hash>
+    """
+
+    def process_packet(self, packet):
+        """
+        Process a packet and extract JA4S fingerprint if applicable.
+
+        Args:
+            packet: A network packet to analyze
+
+        Returns:
+            The extracted fingerprint if successful, None otherwise
+        """
+        fingerprint = generate_ja4s(packet)
+        if fingerprint:
+            self.add_fingerprint(fingerprint, packet)
+            return fingerprint
+        return None
+
+
+def generate_ja4s(packet):
+    """
+    Generate a JA4S fingerprint from a packet.
+
+    Args:
+        packet: A packet containing a TLS Server Hello message
+
+    Returns:
+        A JA4S fingerprint string or None if not applicable
+    """
+    # Extract TLS info
+    tls_info = extract_tls_info(packet)
+    if not tls_info or tls_info.get('handshake_type') != 'server_hello':
+        return None
+
+    try:
+        # Protocol indicator (t for TCP/TLS, q for QUIC, d for DTLS)
+        proto = 'q' if tls_info.get('is_quic') else 'd' if tls_info.get('is_dtls') else 't'
+
+        # Get TLS version - check supported_versions first (for TLS 1.3)
+        version = tls_info.get('version')
+        supported_versions = tls_info.get('supported_versions', [])
+        if supported_versions:
+            non_grease = [v for v in supported_versions if not is_grease_value(v)]
+            if non_grease:
+                version = non_grease[0]
+
+        version_str = _version_to_str(version)
+
+        # Get extensions - JA4S INCLUDES GREASE values per FoxIO spec
+        # (unlike JA4 client which excludes them)
+        extensions = tls_info.get('extensions', [])
+        ext_count = f"{min(len(extensions), 99):02d}"
+
+        # Extract ALPN - use first and last character of first protocol
+        alpn_protocols = tls_info.get('alpn_protocols', [])
+        if not alpn_protocols:
+            # Check extension_data for backward compatibility
+            for ext_id, ext_data in tls_info.get('extension_data', {}).items():
+                if ext_id == 0x0010 and 'protocols' in ext_data and ext_data['protocols']:
+                    alpn_protocols = ext_data['protocols']
+                    break
+
+        alpn_value = _get_alpn_value(alpn_protocols)
+
+        # Form part_a of the fingerprint
+        part_a = f"{proto}{version_str}{ext_count}{alpn_value}"
+
+        # Get selected cipher
+        cipher = tls_info.get('cipher')
+        if cipher is None:
+            return None
+        cipher_str = f"{cipher:04x}"
+
+        # Hash the extensions as comma-separated hex values
+        # JA4S extensions are NOT sorted - they maintain original order per spec
+        # JA4S INCLUDES GREASE values in the hash per FoxIO spec
+        if extensions:
+            ext_str = ','.join([f"{e:04x}" for e in extensions])
+            extensions_hash = hashlib.sha256(ext_str.encode()).hexdigest()[:12]
+        else:
+            extensions_hash = '000000000000'
+
+        # Form the complete JA4S fingerprint
+        ja4s = f"{part_a}_{cipher_str}_{extensions_hash}"
+
+        return ja4s
+
+    except Exception:
+        return None
+
+
+def _version_to_str(version):
+    """Convert TLS version number to JA4 version string."""
+    version_map = {
+        0x0304: '13',  # TLS 1.3
+        0x0303: '12',  # TLS 1.2
+        0x0302: '11',  # TLS 1.1
+        0x0301: '10',  # TLS 1.0
+        0x0300: 's3',  # SSL 3.0
+        0x0200: 's2',  # SSL 2.0
+        0xfeff: 'd1',  # DTLS 1.0
+        0xfefd: 'd2',  # DTLS 1.2
+        0xfefc: 'd3',  # DTLS 1.3
+    }
+    return version_map.get(version, '00')
+
+
+def _get_alpn_value(alpn_protocols):
+    """
+    Extract ALPN value for JA4S fingerprint.
+    Per FoxIO spec: first and last char of first protocol.
+    Non-ASCII (ord > 127) -> '99'.
+    """
+    if not alpn_protocols:
+        return '00'
+
+    first_alpn = alpn_protocols[0]
+    if not first_alpn:
+        return '00'
+
+    # FoxIO spec: if first char is non-ASCII, use '99'
+    if ord(first_alpn[0]) > 127:
+        return '99'
+
+    if len(first_alpn) == 1:
+        return first_alpn[0] + first_alpn[0]
+
+    return f"{first_alpn[0]}{first_alpn[-1]}"