@anonympins/fingerprint 0.3.4 → 0.3.5

package/src/php/Ja3AnomalyDetector.php

@@ -0,0 +1,228 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint;
+
+/**
+ * Classe de détection d'anomalies et d'usurpation TLS (JA3) en PHP.
+ */
+class Ja3AnomalyDetector
+{
+    // Liste décimale des valeurs GREASE (RFC 8701) utilisées par les moteurs Chromium/Safari récents
+    private const GREASE_VALUES = [
+        2570, 6682, 10794, 14906, 19018, 23130, 27242, 31354,
+        35466, 39578, 43690, 47802, 51914, 55926, 60038, 64150
+    ];
+
+    // Base de données locale de signatures JA3 MD5 connues pour la corroboration de base
+    private const TLS_FINGERPRINT_DB = [
+        'e188a442b87f422c5a1e80b05399435b' => ['Chrome'],
+        'd8e35855049321c6042a4325c697858f' => ['Chrome'],
+        'a9f90958d44533748c139a5d1895b925' => ['Chrome'],
+        '3b5379916d2b3882253c42885956a350' => ['Chrome'],
+        '59822058c95c33d2d06e52f410855c8c' => ['Chrome'],
+        'b386946a5a586163c7c533636b45c355' => ['Firefox'],
+        '66236495a523c1785f8f3a105b248b11' => ['Firefox'],
+        'b73d470006575b5e35167a0b5a8540e2' => ['Firefox'],
+        '8443d7562933834333943465d52363cf' => ['Firefox'],
+        'b633f21d532d35967c8753c38536b4d3' => ['Safari'],
+        '4d7a28d5f55b359b69100a311013f03e' => ['Safari', 'Chrome', 'Firefox'],
+        '8dd3d7532873575314df23c447543001' => ['Safari', 'Chrome', 'Firefox'],
+        // Bibliothèques et scrapers automatisés connus
+        '47344a349b75c4e82333475553b5f358' => ['Python'],
+        'b29587b8a143c42546133ad7704b3310' => ['Go'],
+        'd435b5223b2884c5a832b842637e245f' => ['Java'],
+        'c72366b9551263d990b7fa574225332c' => ['curl'],
+    ];
+
+    /**
+     * Analyse une chaîne JA3 brute non hachée.
+     * Format attendu : "TLSVersion,Ciphers,Extensions,EllipticCurves,EllipticCurveFormats"
+     */
+    public static function parseJa3(string $ja3String): ?array
+    {
+        if (empty($ja3String)) {
+            return null;
+        }
+
+        $parts = explode(',', $ja3String);
+        if (count($parts) !== 5) {
+            return null;
+        }
+
+        return [
+            'tlsVersion' => (int)$parts[0],
+            'ciphers'    => $parts[1] !== '' ? array_map('intval', explode('-', $parts[1])) : [],
+            'extensions' => $parts[2] !== '' ? array_map('intval', explode('-', $parts[2])) : [],
+            'curves'     => $parts[3] !== '' ? array_map('intval', explode('-', $parts[3])) : [],
+            'points'     => $parts[4] !== '' ? array_map('intval', explode('-', $parts[4])) : []
+        ];
+    }
+
+    /**
+     * Vérifie si un tableau contient au moins une valeur GREASE.
+     */
+    public static function hasGrease(array $values): bool
+    {
+        foreach ($values as $val) {
+            if (in_array($val, self::GREASE_VALUES, true)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Parse sommairement le User-Agent pour en extraire la famille de navigateur.
+     */
+    public static function getBrowserFamily(string $userAgent): ?string
+    {
+        $ua = strtolower($userAgent);
+        if (strpos($ua, 'edg') !== false) {
+            return 'Edge';
+        }
+        if (strpos($ua, 'chrome') !== false) {
+            return 'Chrome';
+        }
+        if (strpos($ua, 'firefox') !== false) {
+            return 'Firefox';
+        }
+        if (strpos($ua, 'safari') !== false) {
+            return 'Safari';
+        }
+        return null;
+    }
+
+    /**
+     * Calcule le score global d'anomalie et d'usurpation JA3.
+     * 
+     * @param string|null $ja3Hash L'empreinte MD5 du JA3 (32 caractères)
+     * @param string|null $ja3Raw L'empreinte brute non hachée (si disponible)
+     * @param string $userAgent Le User-Agent de la requête
+     * @param string $httpVersion La version HTTP de la requête (ex: "HTTP/2", "HTTP/1.1", ou "2.0")
+     * @param object|null $cacheInstance Un driver de cache (ex: instance Redis) supportant get() et set() pour la détection de stagnation
+     * @return int Un score de suspicion compris entre 0 et 100
+     */
+    public static function getJa3AnomalyScore(
+        ?string $ja3Hash,
+        ?string $ja3Raw,
+        string $userAgent,
+        string $httpVersion,
+        ?object $cacheInstance = null
+    ): int {
+        $score = 0;
+        $claimedBrowser = self::getBrowserFamily($userAgent);
+        $isHumanBrowser = in_array($claimedBrowser, ['Chrome', 'Firefox', 'Safari', 'Edge'], true);
+
+        // --- ANALYSE 1 : CONTRÔLE SUR LE MD5 DU JA3 ---
+        if ($ja3Hash && strlen($ja3Hash) === 32) {
+            if (isset(self::TLS_FINGERPRINT_DB[$ja3Hash])) {
+                $expectedBrowsers = self::TLS_FINGERPRINT_DB[$ja3Hash];
+
+                // Cas A : L'empreinte correspond à un outil de scraping mais le UA prétend être humain
+                $isLibrary = array_intersect($expectedBrowsers, ['Python', 'Go', 'Java', 'curl']);
+                if (!empty($isLibrary) && $isHumanBrowser) {
+                    $score = max($score, 90); // Suspicion maximale : usurpation évidente
+                }
+                
+                // Cas B : Incohérence directe entre le UA prétendu et la stack TLS correspondante
+                if ($claimedBrowser !== null) {
+                    $matched = false;
+                    foreach ($expectedBrowsers as $expected) {
+                        if (stripos($claimedBrowser, $expected) === 0) {
+                            $matched = true;
+                            break;
+                        }
+                    }
+                    if (!$matched) {
+                        $score = max($score, 80); // Le navigateur déclaré ne correspond pas au client TLS utilisé
+                    }
+                }
+            }
+
+            // Cas C : Tracking de stagnation multi-UA (Stateful)
+            if ($cacheInstance && $claimedBrowser !== null && method_exists($cacheInstance, 'get') && method_exists($cacheInstance, 'set')) {
+                $cacheKey = "ja3-browsers:" . $ja3Hash;
+                
+                try {
+                    $rawCached = $cacheInstance->get($cacheKey);
+                    $seenBrowsers = $rawCached ? json_decode((string)$rawCached, true) : [];
+                    if (!is_array($seenBrowsers)) {
+                        $seenBrowsers = [];
+                    }
+
+                    if (!in_array($claimedBrowser, $seenBrowsers, true)) {
+                        $seenBrowsers[] = $claimedBrowser;
+                        // Cache pendant 24 heures (86400 secondes)
+                        if (method_exists($cacheInstance, 'setex')) {
+                            $cacheInstance->setex($cacheKey, 86400, json_encode($seenBrowsers));
+                        } else {
+                            $cacheInstance->set($cacheKey, json_encode($seenBrowsers), 86400);
+                        }
+                    }
+
+                    // Si une seule stack TLS génère des requêtes avec différents navigateurs, c'est un bot en rotation de UA
+                    if (count($seenBrowsers) > 1) {
+                        $score = max($score, 85);
+                    }
+                } catch (\Throwable $e) {
+                    // Tolérance aux pannes du cache
+                }
+            }
+        }
+
+        // --- ANALYSE 2 : CONTRÔLE PROFOND SUR L'EMPREINTE BRUTE (RAW JA3) ---
+        if ($ja3Raw) {
+            $parsed = self::parseJa3($ja3Raw);
+            if ($parsed) {
+                // Contrôle A : Mécanisme GREASE pour Chrome / Edge (obligatoire)
+                if ($claimedBrowser === 'Chrome' || $claimedBrowser === 'Edge') {
+                    $hasCiphersGrease = self::hasGrease($parsed['ciphers']);
+                    $hasExtensionsGrease = self::hasGrease($parsed['extensions']);
+                    
+                    if (!$hasCiphersGrease && !$hasExtensionsGrease) {
+                        // Chrome ou Edge moderne sans GREASE = spoofing de bas niveau (ex: python-requests déguisé)
+                        $score = max($score, 75);
+                    }
+                }
+
+                // Contrôle B : HTTP/2 ou HTTP/3 sans négociation ALPN (Extension 16)
+                $isH2OrHigher = (
+                    strpos($httpVersion, '2.0') !== false || 
+                    strpos($httpVersion, 'HTTP/2') !== false || 
+                    strpos($httpVersion, 'HTTP/3') !== false
+                );
+                $hasAlpnExtension = in_array(16, $parsed['extensions'], true);
+                
+                if ($isH2OrHigher && !$hasAlpnExtension) {
+                    // Négociation HTTP/2 active au niveau serveur mais absente au niveau des extensions TLS du client
+                    $score = max($score, 70);
+                }
+
+                // Contrôle C : Version TLS obsolète négociée par un navigateur moderne (ex: TLS < 1.2, id < 771)
+                if ($isHumanBrowser && $parsed['tlsVersion'] < 771) {
+                    $score = max($score, 80);
+                }
+            }
+        }
+
+        return $score;
+    }
+}
+
+// --- EXEMPLE D'UTILISATION PRATIQUE ---
+/*
+$userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
+$httpVersion = $_SERVER['SERVER_PROTOCOL'] ?? '';
+
+// Récupération des en-têtes injectés par votre Reverse-Proxy (Nginx, HAProxy, etc.)
+$ja3Hash = $_SERVER['HTTP_X_JA3_HASH'] ?? null;
+$ja3Raw  = $_SERVER['HTTP_X_JA3_RAW'] ?? null; 
+
+// Redis facultatif pour la détection stateful de rotation UA
+$redis = new \Redis();
+$redis->connect('127.0.0.1', 6379);
+
+$suspicionScore = Ja3AnomalyDetector::getJa3AnomalyScore($ja3Hash, $ja3Raw, $userAgent, $httpVersion, $redis);
+*/

package/src/php/Tests/Ja3AnomalyDetectorTest.php

@@ -0,0 +1,180 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Anonympins\Fingerprint\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Anonympins\Fingerprint\Ja3AnomalyDetector;
+
+/**
+ * Tests unitaires pour la classe Ja3AnomalyDetector.
+ */
+class Ja3AnomalyDetectorTest extends TestCase
+{
+    /**
+     * Teste le parsing d'une chaîne JA3 brute valide.
+     */
+    public function testParseJa3ValidString(): void
+    {
+        $ja3 = '771,4865-4866-4867,0-23-65281-10-11,29-23-24,0';
+        $parsed = Ja3AnomalyDetector::parseJa3($ja3);
+
+        $this->assertNotNull($parsed);
+        $this->assertSame(771, $parsed['tlsVersion']);
+        $this->assertSame([4865, 4866, 4867], $parsed['ciphers']);
+        $this->assertSame([0, 23, 65281, 10, 11], $parsed['extensions']);
+        $this->assertSame([29, 23, 24], $parsed['curves']);
+        $this->assertSame([0], $parsed['points']);
+    }
+
+    /**
+     * Teste le parsing avec des valeurs manquantes ou malformées.
+     */
+    public function testParseJa3InvalidString(): void
+    {
+        $this->assertNull(Ja3AnomalyDetector::parseJa3(''));
+        $this->assertNull(Ja3AnomalyDetector::parseJa3('771,4865,0-23')); // Moins de 5 parties
+    }
+
+    /**
+     * Teste la détection du mécanisme GREASE.
+     */
+    public function testHasGrease(): void
+    {
+        // Contient la valeur GREASE 2570 (0x0A0A)
+        $this->assertTrue(Ja3AnomalyDetector::hasGrease([4865, 2570, 4866]));
+        // Ne contient pas de valeur GREASE
+        $this->assertFalse(Ja3AnomalyDetector::hasGrease([4865, 4866, 4867]));
+    }
+
+    /**
+     * Teste l'extraction de la famille du User-Agent.
+     */
+    public function testGetBrowserFamily(): void
+    {
+        $this->assertSame('Chrome', Ja3AnomalyDetector::getBrowserFamily('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'));
+        $this->assertSame('Edge', Ja3AnomalyDetector::getBrowserFamily('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0'));
+        $this->assertSame('Firefox', Ja3AnomalyDetector::getBrowserFamily('Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:120.0) Gecko/20100101 Firefox/120.0'));
+        $this->assertSame('Safari', Ja3AnomalyDetector::getBrowserFamily('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15'));
+        $this->assertNull(Ja3AnomalyDetector::getBrowserFamily('curl/7.68.0'));
+    }
+
+    /**
+     * Teste la détection d'usurpation d'une bibliothèque connue (ex: Python/Go/curl).
+     */
+    public function testSpoofingLibraryDetected(): void
+    {
+        $pythonJa3 = '47344a349b75c4e82333475553b5f358'; // Signature Python dans DB
+        $userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore($pythonJa3, null, $userAgent, 'HTTP/2');
+
+        // Devrait retourner un score élevé (90) car une signature python se fait passer pour Chrome
+        $this->assertEquals(90, $score);
+    }
+
+    /**
+     * Teste la détection d'une incohérence de navigateur (ex: signature Firefox avec UA Chrome).
+     */
+    public function testBrowserMismatchDetected(): void
+    {
+        $firefoxJa3 = 'b386946a5a586163c7c533636b45c355'; // Signature Firefox dans DB
+        $userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore($firefoxJa3, null, $userAgent, 'HTTP/2');
+
+        $this->assertEquals(80, $score);
+    }
+
+    /**
+     * Teste la détection de stagnation de hash avec rotation d'User-Agents.
+     */
+    public function testStagnationWithRotatingUserAgents(): void
+    {
+        // Mock d'un stockage de cache minimal en mémoire
+        $cache = new class {
+            private array $store = [];
+            public function get(string $key): ?string { return $this->store[$key] ?? null; }
+            public function set(string $key, string $val, int $ttl = 0): void { $this->store[$key] = $val; }
+            public function setex(string $key, int $ttl, string $val): void { $this->store[$key] = $val; }
+        };
+
+        $unknownJa3 = '00000000000000000000000000000000';
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        $firefoxUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Firefox/120.0';
+
+        // Premier appel avec Chrome -> pas d'anomalie de stagnation encore
+        $score1 = Ja3AnomalyDetector::getJa3AnomalyScore($unknownJa3, null, $chromeUA, 'HTTP/2', $cache);
+        $this->assertLessThan(85, $score1);
+
+        // Deuxième appel avec la même stack TLS mais un UA Firefox -> Détection de rotation !
+        $score2 = Ja3AnomalyDetector::getJa3AnomalyScore($unknownJa3, null, $firefoxUA, 'HTTP/2', $cache);
+        $this->assertEquals(85, $score2);
+    }
+
+    /**
+     * Teste l'absence de valeurs GREASE pour un navigateur Chromium.
+     */
+    public function testMissingGreaseForChrome(): void
+    {
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        // JA3 brut valide mais sans AUCUNE valeur GREASE dans les extensions ou les ciphers
+        $ja3RawWithoutGrease = '771,4865-4866,0-23-10,29,0';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore(null, $ja3RawWithoutGrease, $chromeUA, 'HTTP/2');
+        $this->assertEquals(75, $score);
+    }
+
+    /**
+     * Teste le cas légitime d'un navigateur Chromium disposant de GREASE.
+     */
+    public function testLegitimateChromeWithGrease(): void
+    {
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        // 2570 est une valeur GREASE valide
+        $ja3RawWithGrease = '771,4865-2570,0-23-10,29,0';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore(null, $ja3RawWithGrease, $chromeUA, 'HTTP/2');
+        $this->assertLessThan(75, $score);
+    }
+
+    /**
+     * Teste la détection d'absence d'ALPN lors de connexions HTTP/2.
+     */
+    public function testHttp2WithoutAlpnExtension(): void
+    {
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        // Pas d'extension 16 (ALPN) dans les extensions
+        $ja3RawNoAlpn = '771,4865-2570,0-23-10,29,0';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore(null, $ja3RawNoAlpn, $chromeUA, 'HTTP/2');
+        $this->assertEquals(70, $score);
+    }
+
+    /**
+     * Teste la présence d'ALPN lors de connexions HTTP/2 (cas normal).
+     */
+    public function testHttp2WithAlpnExtension(): void
+    {
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        // L'extension 16 est présente
+        $ja3RawWithAlpn = '771,4865-2570,0-23-10-16,29,0';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore(null, $ja3RawWithAlpn, $chromeUA, 'HTTP/2');
+        $this->assertLessThan(70, $score);
+    }
+
+    /**
+     * Teste l'utilisation d'une version obsolète de TLS par un navigateur récent.
+     */
+    public function testObsoleteTlsVersionWithModernBrowser(): void
+    {
+        $chromeUA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0';
+        // Version TLS 769 (TLS 1.0) initiée par un Chrome récent
+        $obsoleteTlsJa3 = '769,4865-2570,0-23-10-16,29,0';
+
+        $score = Ja3AnomalyDetector::getJa3AnomalyScore(null, $obsoleteTlsJa3, $chromeUA, 'HTTP/2');
+        $this->assertEquals(80, $score);
+    }
+}

package/src/php/Utils/RequestUtils.php

@@ -186,7 +186,7 @@ class RequestUtils
     public static function getHeaderAnomalies(RequestContext $context): array
     {
         $anomalyScore = 0;
-        $ua = $context->getHeader('user-agent');
+        $ua = $context->getHeader('user-agent') ?? '';
         if (empty($ua) || strlen($ua) < 10) {
             $anomalyScore += 60;
         }
@@ -197,6 +197,17 @@ class RequestUtils
             $anomalyScore += 15;
         }
 
+        // TE: trailers check for Firefox on Desktop
+        $uaParts = self::parseUserAgent($ua);
+        $isFirefoxDesktop = isset($uaParts['browser']) && str_starts_with($uaParts['browser'], 'Firefox') && ($uaParts['device'] ?? 'desktop') === 'desktop';
+        $te = strtolower($context->getHeader('te') ?? '');
+
+        if ($isFirefoxDesktop && $te !== 'trailers') {
+            $anomalyScore += 30;
+        } elseif (!$isFirefoxDesktop && ($uaParts['device'] ?? 'desktop') === 'desktop' && $te === 'trailers') {
+            $anomalyScore += 30;
+        }
+
         return ['headerAnomalyScore' => min(100.0, $anomalyScore)];
     }
 
@@ -520,7 +531,7 @@ class RequestUtils
             $deviceData['lastChangeTimestamp'] = $now;
         }
         $deviceData['lastFpHash'] = $currentFpHash;
-        
+
         // Enregistrement de l'IP
         if (!in_array($clientIp, $deviceData['ips'])) {
             $deviceData['ips'][] = $clientIp;
@@ -749,7 +760,7 @@ class RequestUtils
      * Parse une chaîne de requête GraphQL pour extraire le type et le nom de l'opération.
      * @param array<string, mixed> $body Le corps de la requête.
      * @return array{type: string, name: string}|null
-     */    
+     */
     public static function parseGraphQLQuery(array $body): ?array
     {
         $query = $body['query'] ?? null;
@@ -841,7 +852,7 @@ class RequestUtils
         if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
             $ipBinary = inet_pton($ip);
             if ($ipBinary === false) return null;
-            
+
             $mask = self::generateMask($ipv4Prefix, 4);
             if ($mask === null) return null;
 
@@ -850,7 +861,7 @@ class RequestUtils
         } elseif (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
             $ipBinary = inet_pton($ip);
             if ($ipBinary === false) return null;
-            
+
             $mask = self::generateMask($ipv6Prefix, 16);
             if ($mask === null) return null;