PHPBotDetect.php

<?php
declare(strict_types=1);

/**
 * PHPBotDetect — a dependency-free bot detector for PHP 8.1+.
 *
 * Detects bots based on: User-Agent signatures (search engines, social media,
 * security tools, HTTP libraries, headless browsers, scrapers), HTTP header
 * analysis, IP membership in known data center ranges, reverse-DNS
 * verification of known bots (e.g. Googlebot), and behavioral analysis
 * (request frequency) plus honeypot detection.
 *
 * Author: Jarosław Szulc <https://psyll.com/jarek> / Psyll.com <https://psyll.com>
 * Repo: https://github.com/psyll/bot-detect
 * License: MIT
 */
final class PHPBotDetect
{
    private const BOT_THRESHOLD = 0.7;
    private const HEADER_ANALYSIS_WEIGHT = 0.75;

    /**
     * Base directory where the library keeps logs and cache (rDNS, behavior).
     * Default: the system tmp directory + "/bot-detect". Can be overridden via
     * PHPBotDetect::setBaseDirectory('/path/to/a/writable/directory').
     */
    private static ?string $baseDirectory = null;

    /**
     * Sets the base directory for logs and cache. Must be writable by PHP.
     * Call this once, at application startup, before using detect().
     */
    public static function setBaseDirectory(string $directory): void
    {
        self::$baseDirectory = rtrim($directory, '/\\');
    }

    private static function baseDirectory(): string
    {
        if (self::$baseDirectory !== null) {
            return self::$baseDirectory;
        }
        return rtrim(sys_get_temp_dir(), '/\\') . '/bot-detect';
    }

    private static function logDirectory(): string
    {
        return self::baseDirectory() . '/logs';
    }

    private static function dnsCacheDirectory(): string
    {
        return self::baseDirectory() . '/dns_cache';
    }

    private static function behaviorStateDirectory(): string
    {
        return self::baseDirectory() . '/behavior';
    }

    public const CATEGORY_SEARCH_ENGINE = 'search_engine';
    public const CATEGORY_SOCIAL_MEDIA = 'social_media';
    public const CATEGORY_SECURITY_TOOL = 'security_tool';
    public const CATEGORY_HTTP_LIBRARY = 'http_library';
    public const CATEGORY_HEADLESS_BROWSER = 'headless_browser';
    public const CATEGORY_CLOUD_HOSTING = 'cloud_hosting';
    public const CATEGORY_SCRAPER = 'scraper';
    public const CATEGORY_UNKNOWN_BOT = 'unknown_bot';
    public const CATEGORY_SPOOFED_BOT = 'spoofed_bot';
    public const CATEGORY_HONEYPOT_TRIGGER = 'honeypot_trigger';
    public const CATEGORY_BEHAVIORAL = 'behavioral';

    /** Cache TTL for rDNS verification of known bots (Google/Bing/etc.), in seconds */
    private const DNS_VERIFY_CACHE_TTL = 86400;

    /** Threshold and TTL for the behavioral trace (request frequency per IP) */
    private const BEHAVIOR_MIN_INTERVAL_SECONDS = 0.35;
    private const BEHAVIOR_STATE_TTL = 300;

    /** Name of the trap (honeypot) field added to forms; must remain empty */
    public const HONEYPOT_FIELD_NAME = 'website_url_confirm';

    /**
     * CIDR ranges of known hosting/cloud/VPS/proxy networks.
     * Non-exhaustive list — deliberately limited to large, stable blocks
     * of the biggest providers, to avoid false positives.
     */
    private static array $dataCenterCidrRanges = [
        // Amazon AWS
        '3.0.0.0/9', '13.32.0.0/15', '15.177.0.0/18', '18.130.0.0/16',
        '34.192.0.0/10', '35.152.0.0/16', '52.0.0.0/8', '54.64.0.0/10',
        // Google Cloud
        '34.64.0.0/10', '34.128.0.0/10', '35.184.0.0/13', '35.192.0.0/14',
        // Microsoft Azure
        '13.64.0.0/11', '20.33.0.0/16', '20.36.0.0/14', '40.64.0.0/10',
        '52.224.0.0/11',
        // DigitalOcean
        '104.131.0.0/16', '104.236.0.0/16', '138.68.0.0/16', '142.93.0.0/16',
        '157.230.0.0/16', '159.65.0.0/16', '159.89.0.0/16', '164.90.0.0/16',
        '167.71.0.0/16', '167.99.0.0/16', '178.62.0.0/16', '188.166.0.0/16',
        '206.189.0.0/16',
        // OVH
        '51.68.0.0/16', '51.75.0.0/16', '51.83.0.0/16', '54.36.0.0/14',
        '141.94.0.0/16', '145.239.0.0/16', '148.113.0.0/16', '158.69.0.0/16',
        '178.32.0.0/15', '188.165.0.0/16',
        // Hetzner
        '5.9.0.0/16', '78.46.0.0/15', '88.99.0.0/16', '116.202.0.0/15',
        '135.181.0.0/16', '138.201.0.0/16', '148.251.0.0/16', '176.9.0.0/16',
        '195.201.0.0/16',
        // Linode/Akamai
        '45.33.0.0/16', '45.56.0.0/16', '45.79.0.0/16', '96.126.96.0/19',
        '139.144.0.0/16', '172.104.0.0/15', '172.105.0.0/16',
        // Vultr
        '45.32.0.0/16', '45.63.0.0/16', '45.76.0.0/16', '66.42.0.0/16',
        '104.156.224.0/19', '108.61.0.0/16', '149.28.0.0/16', '207.148.0.0/17',
        // Oracle Cloud
        '129.146.0.0/16', '132.145.0.0/16', '140.238.0.0/16', '150.230.0.0/16',
        // Contabo
        '5.189.128.0/17', '144.126.128.0/18', '154.53.128.0/17', '213.136.64.0/18',
        // Alibaba Cloud
        '47.74.0.0/15', '47.88.0.0/14', '47.244.0.0/16', '8.208.0.0/13',
    ];

    /**
     * Reverse-DNS domains accepted as "genuine" for a given engine,
     * used to verify that a bot declaring itself as e.g. Googlebot
     * actually connects from Google's network.
     */
    private static array $trustedReverseDnsSuffixes = [
        'google' => ['.googlebot.com', '.google.com'],
        'bing' => ['.search.msn.com'],
        'yandex' => ['.yandex.ru', '.yandex.net', '.yandex.com'],
        'duckduckgo' => ['.duckduckgo.com'],
        'baidu' => ['.baidu.com', '.baidu.jp'],
        'apple' => ['.applebot.apple.com'],
        'openai' => ['.chatgpt.com', '.openai.com'],
        'anthropic' => ['.anthropic.com', '.crawl.claude.com'],
    ];
    private static array $searchEngineBots = [
        'Googlebot' => 'google',
        'Googlebot-Image' => 'google',
        'Googlebot-News' => 'google',
        'Googlebot-Video' => 'google',
        'Googlebot-Mobile' => 'google',
        'GoogleOther' => 'google',
        'GoogleOther-Image' => 'google',
        'GoogleOther-Video' => 'google',
        'Google-InspectionTool' => 'google',
        'Google-Safety' => 'google',
        'Google-Extended' => 'google',
        'Google-CloudVertexBot' => 'google',
        'APIs-Google' => 'google',
        'AdsBot-Google' => 'google',
        'AdsBot-Google-Mobile' => 'google',
        'Mediapartners-Google' => 'google',
        'FeedFetcher-Google' => 'google',
        'Storebot-Google' => 'google',
        'GoogleProducer' => 'google',
        'bingbot' => 'bing',
        'BingPreview' => 'bing',
        'msnbot' => 'bing',
        'adidxbot' => 'bing',
        'Baiduspider' => 'baidu',
        'YandexBot' => 'yandex',
        'YandexImages' => 'yandex',
        'YandexMobileBot' => 'yandex',
        'DuckDuckBot' => 'duckduckgo',
        'Sogou web spider' => 'sogou',
        'sogouspider' => 'sogou',
        'Exabot' => 'exalead',
        'coccocbot' => 'coccoc',
        'SeznamBot' => 'seznam',
        'Mojeek' => 'mojeek',
        'ia_archiver' => 'alexa_archive',
        'Yeti' => 'naver',
        'YisouSpider' => 'yisou',
        'PetalBot' => 'huawei_petal',
        'Petalbot' => 'huawei_petal',
        'GPTBot' => 'openai',
        'ChatGPT-User' => 'openai',
        'OAI-SearchBot' => 'openai',
        'ClaudeBot' => 'anthropic',
        'Claude-User' => 'anthropic',
        'Claude-SearchBot' => 'anthropic',
        'anthropic-ai' => 'anthropic',
        'PerplexityBot' => 'perplexity',
        'Perplexity-User' => 'perplexity',
        'Amazonbot' => 'amazon',
        'Bytespider' => 'bytedance',
        'meta-externalagent' => 'meta',
        'FacebookBot' => 'meta',
        'xAI-SearchBot' => 'xai',
        'Applebot' => 'apple',
        'Applebot-Extended' => 'apple',
    ];
    private static array $socialMediaBots = [
        'facebookexternalhit',
        'FacebookBot',
        'facebookscraper',
        'Twitterbot',
        'LinkedInBot',
        'WhatsApp',
        'TelegramBot',
        'Slackbot',
        'Slack-ImgProxy',
        'Discordbot',
        'SkypeUriPreview',
        'redditbot',
        'Pinterest',
        'Pinterestbot',
        'MicroMessenger',
        'FlipboardProxy',
        'Iframely',
        'Embedly',
        'Bluesky Cardyb',
        'Mastodon',
        'Pleroma',
        'Akkoma',
        'Friendica',
        'Misskey',
        'GoogleImageProxy',
        'showyoubot',
        'ShowyouBot',
        'MetaInspector',
        'Vkontakte',
        'Viber',
    ];
    private static array $securityToolMarkers = [
        'nmap',
        'nikto',
        'sqlmap',
        'sqlninja',
        'nessus',
        'openvas',
        'masscan',
        'zmap',
        'zgrab',
        'acunetix',
        'netsparker',
        'appscan',
        'qualys',
        'burp suite',
        'burpcollaborator',
        'w3af',
        'wpscan',
        'dirbuster',
        'fimap',
        'jbrofuzz',
        'havij',
        'whatweb',
        'shodan',
        'censysinspect',
        'gobuster',
        'wprecon',
        'metasploit',
        'nuclei',
        'ffuf',
        'feroxbuster',
        'sublist3r',
        'hydra',
        'medusa',
        'commix',
        'xsser',
        'skipfish',
        'arachni',
        'wafw00f',
        'testssl',
        'sslyze',
    ];
    private static array $httpLibraryMarkers = [
        'curl/',
        'axios',
        'guzzlehttp',
        'python-requests',
        'python-urllib',
        'okhttp',
        'go-http-client',
        'aiohttp',
        'node-fetch',
        'python-httpx',
        'httpx',
        'wget',
        'libcurl',
        'java-http-client',
        'postmanruntime',
        'restsharp',
        'faraday',
        'unirest',
        'apache-httpclient',
        'lwp-',
        'libwww-perl',
        'http_request2',
        'symfony browserkit',
        'typhoeus',
        'sindresorhus/got',
        'http.rb',
        'scalaj-http',
        'mojolicious',
        'pecl::http',
        'poe-component-client-http',
        'jetty',
        'reqwest',
        'ureq',
        'httpclient',
        'dart:io',
        'cfnetwork',
        'winhttp',
        'urlgrabber',
        'urllib3',
        'ktor-client',
        'vert.x-web-client',
    ];
    private static array $headlessBrowserMarkers = [
        'headlesschrome',
        'phantomjs',
        'puppeteer',
        'playwright',
        'selenium',
        'webdriver',
        'electron',
        'slimerjs',
        'nightmarejs',
        'cypress',
        'chrome-lighthouse',
        'headlessfirefox',
    ];
    private static array $cloudHostingMarkers = [
        'amazonaws.com',
        'googleusercontent.com',
        'digitalocean',
        'linode',
        'ovh',
        'hetzner',
        'azure',
        'oraclecloud',
        'alibabacloud',
        'vultr',
        'contabo',
    ];
    private static array $miscBots = [
        '01h4x.com',
        '7Siters',
        '80legs',
        '360Spider',
        '404checker',
        '404enemy',
        '(BOT for JCE)',
        'A6-Indexer',
        'Abonti',
        'Aboundex',
        'acebookexternalhit',
        'Acunetix',
        'AdlesseBot',
        'ADmantX',
        'admantx-adform',
        'Adsbot',
        'adscanner',
        'AfD-Verbotsverfahren',
        'AHC/2.1',
        'AhrefsBot',
        'AIBOT',
        'AiHitBot',
        'aiohttp',
        'Aipbot',
        'Alexibot',
        'ALittle Client',
        'Alligator',
        'AllSubmitter',
        'AlphaBot',
        'Amazing-SearchBot',
        'Anarchie',
        'Anarchy99',
        'Anarchy',
        'Ankit',
        'Anthill',
        'anthropic',
        'Apache-HttpClient/5',
        'ApacheBench',
        'Apexoo',
        'app.hypefactors.com',
        'AppEngine-Google',
        'Aranet',
        'archive.org_bot',
        'ArchiveBot',
        'arquivo-web-crawler',
        'arquivo.pt',
        'Aspiegel',
        'ASPSeek',
        'Asterias',
        'Astute SRM',
        'Atomseobot',
        'Attach',
        'autoemailspider',
        'AwarioBot',
        'AwarioRssBot',
        'AwarioSmartBot',
        'axios',
        'BackDoorBot',
        'Backlink-Ceck',
        'backlink-check',
        'BacklinkCrawler',
        'BackStreet',
        'BackWeb',
        'Badass',
        'baidu',
        'Bandit',
        'Barkrowler',
        'BatchFTP',
        'Battleztar Bazinga',
        'BazQuxBot',
        'BBBike',
        'BDCbot',
        'BDFetch',
        'BehloolBot',
        'BetaBot',
        'Bigfoot',
        'Bitacle',
        'bitlybot',
        'Black Hole',
        'Blackboard',
        'BlackWidow',
        'BLEXBot',
        'Blow',
        'BlowFish',
        'BoardReader',
        'Bolt',
        'BotALot',
        'Brandprotect',
        'Brandwatch',
        'BrokenLinksBot',
        'BTWebClient',
        'BUbiNG',
        'Buck',
        'Buddy',
        'BuiltBotTough',
        'BuiltWith',
        'Bullseye',
        'BunnySlippers',
        'Butterfly',
        'BuzzSumo',
        'cah.io.community',
        'Calculon',
        'CATExplorador',
        'CazoodleBot',
        'CCBot',
        'Cegbfeieh',
        'CensysInspect',
        'ChatGPT',
        'check1.exe',
        'CheeseBot',
        'CherryPicker',
        'CheTeam',
        'ChinaClaw',
        'Chlooe',
        'Citoid',
        'Claritybot',
        'clark-crawler',
        'Claude-Web',
        'Cliqzbot',
        'Cloud mapping',
        'Cloudflare SpeedTest',
        'Cocolyzebot',
        'CODE87',
        'Cogentbot',
        'cognitiveseo',
        'cohere-ai',
        'Collector',
        'com.plumanalytics',
        'commoncrawl',
        'CommonCrawler Node',
        'CommonCrawler',
        'Copier',
        'CopyRightCheck',
        'Copyscape',
        'Cosmos',
        'Craftbot',
        'crawl.sogou.com',
        'crawler',
        'crawler4j',
        'crawler.feedback',
        'Crawling at Home Project',
        'CrazyWebCrawler',
        'Crescent',
        'CriteoBot',
        'CrunchBot',
        'cs.daum.net',
        'CSHttp',
        'Curious',
        'curl/7',
        'Custo',
        'CyotekWebCopy',
        'DatabaseDriverMysqli',
        'DataCha0s',
        'dataforseo.com',
        'DataForSeoBot',
        'Dazzle BlueSky',
        'DBLBot',
        'demandbase-bot',
        'Demon',
        'Deusu',
        'Devil',
        'Diffbot',
        'Digincore',
        'DigitalPebble',
        'DIIbot',
        'Dirbuster',
        'Disco',
        'Discobot',
        'Discoverybot',
        'Dispatch',
        'DittoSpyder',
        'dlvr.it',
        'DnBCrawler-Analytics',
        'DnyzBot',
        'DomainAppender',
        'DomainCrawler',
        'Domains Project',
        'DomainSigmaCrawler',
        'domainsproject.org',
        'DomainStatsBot',
        'DomCopBot',
        'DotBot',
        'Down/5',
        'Download Wonder',
        'Dragonfly',
        'Drip',
        'DSearch',
        'DTS Agent',
        'DuckDuckGo',
        'EasyDL',
        'Ebingbong',
        'eCairn-Grabber',
        'eCatch',
        'ECCP/1.0',
        'Ecxi',
        'EirGrabber',
        'EMail Siphon',
        'EMail Wolf',
        'EroCrawler',
        'ev-crawler',
        'evc-batch',
        'Evil',
        'Express WebPictures',
        'ExtLinksBot',
        'Extractor',
        'ExtractorPro',
        'Extreme Picture Finder',
        'EyeNetIE',
        'Ezooms',
        'FDM',
        'fedistatsCrawler',
        'feedbot',
        'Feeder',
        'Feedly',
        'FemtosearchBot',
        'FHscan',
        'Fimap',
        'Firefox/7.0',
        'FlashGet',
        'Flunky',
        'Foobot',
        'Freeuploader',
        'FreshRSS',
        'FrontPage',
        'Fuzz',
        'FyberSpider',
        'Fyrebot',
        'G-i-g-a-b-o-t',
        'GalaxyBot',
        'GarlikCrawler',
        'Genieo',
        'GermCrawler',
        'Getintent',
        'GetRight',
        'getstream.io/winds',
        'GetWeb',
        'Giant Rhubarb',
        'GigablastOpenSource/1.0',
        'Gigabot',
        'Gluten Free Crawler',
        'glutenfreepleasure.com',
        'Go!Zilla',
        'Go-Ahead-Got-It',
        'Go-http-client',
        'Google-Apps-Scrip',
        'gopher',
        'Gotit',
        'GoZilla',
        'GozleBot',
        'Grabber',
        'GrabNet',
        'Grafula',
        'GrapeFX',
        'GrapeshotCrawler',
        'GridBot',
        'grokkit-crawler',
        'GroupHigh',
        'GT::WWW',
        'GuzzleHttp',
        'Haansoft',
        'HaosouSpider',
        'Harvest',
        'Havij',
        'HEADMasterSEO',
        'heritrix',
        'Hloader',
        'HMView',
        'HonoluluBot',
        'HTMLparser',
        'http.rb',
        'HTTP::Lite',
        'HTTP_Request2',
        'HTTrack',
        'Humanlinks',
        'HybridBot',
        'IABot',
        'iaskspider',
        'Iblog',
        'IbouBot',
        'ibwww-perl',
        'Id-search',
        'IDBot',
        'IDBTE4M',
        'IlseBot',
        'Image Fetch',
        'Image Sucker',
        'ImageFetcher',
        'imagesift',
        'ImagesiftBot',
        'InAGist',
        'IndeedBot',
        'Indy Library',
        'InfoNaviRobot',
        'InfoTekies',
        'instabid',
        'Instapaper',
        'Intelliseek',
        'InterGET',
        'Internet Ninja',
        'InternetMeasurement',
        'InternetSeer',
        'internetVista monitor',
        'ips-agent',
        'Iria',
        'IRLbot',
        'isitwp.com',
        'Iskanie',
        'IstellaBot',
        'iubenda-radar',
        'JamesBOT',
        'Java/1.8',
        'Jbrofuzz',
        'JennyBot',
        'JetCar',
        'Jetslide',
        'Jetty',
        'JikeSpider',
        'JOC Web Spider',
        'Joomla',
        'Jorgee',
        'JustView',
        'Jyxobot',
        'KatBot',
        'Kenjin Spider',
        'Keybot Translation-Search-Machine',
        'keys-so-bot',
        'Keyword Density',
        'Kinza',
        'koyu.space',
        'Kozmosbot',
        'Kraken',
        'Lanshanbot',
        'Larbin',
        'LCC',
        'leakix.net',
        'Leap',
        'LeechFTP',
        'LeechGet',
        'LexiBot',
        'Lftp',
        'LibWeb',
        'Libwhisker',
        'libwww-perl',
        'LieBaoFast',
        'Lightspeedsystems',
        'Likse',
        'Linguee Bot',
        'Linkbot',
        'linkdex',
        'linkdexbot',
        'LinkextractorPro',
        'linkfluence.com',
        'LinkpadBot',
        'LinkScan',
        'LinksManager',
        'LinkWalker',
        'LinqiaMetadataDownloaderBot',
        'LinqiaRSSBot',
        'LinqiaScrapeBot',
        'Lipperhey Spider',
        'Lipperhey',
        'Litemage_walker',
        'LivelapBot',
        'Lmspider',
        'LNSpiderguy',
        'ltx71',
        'lwp-request',
        'lwp-trivial',
        'LWP::Simple',
        'Mag-Net',
        'Magnet',
        'magpie-crawler',
        'Mail.RU_Bot',
        'Majestic12',
        'Majestic SEO',
        'Majestic-SEO',
        'MarkMonitor',
        'MarkWatch',
        'Mass Downloader',
        'Masscan',
        'Mata Hari',
        'MauiBot',
        'MaxPointCrawler',
        'Mb2345Browser',
        'MeanPath Bot',
        'Meanpathbot',
        'Mediatoolkitbot',
        'mediawords bot',
        'mediawords',
        'MegaIndex',
        'merlinkbot',
        'metadataparser',
        'MetadataScraper',
        'MetaJobBot',
        'metauri',
        'MFC_Tear_Sample',
        'Microsoft Data Access',
        'Microsoft Office',
        'Microsoft URL Control',
        'MIDown tool',
        'MIIxpc',
        'Minefield',
        'Miniflux',
        'Mister PiX',
        'MistralBot',
        'MJ12bot',
        'Mjukisbyxor',
        'Moblie Safari',
        'Mojolicious',
        'MolokaiBot',
        'mon.itor.us',
        'monitoring-plugins',
        'Moreover',
        'Morfeus Fucking Scanner',
        'Mozlila',
        'MQQBrowser',
        'Mr.4x3',
        'MSFrontPage',
        'MSIECrawler',
        'Msrabot',
        'MTRobot',
        'MuckRack',
        'muhstik-scan',
        'Musobot',
        'Name Intelligence',
        'Nameprotect',
        'Navroad',
        'NearSite',
        'Needle',
        'Neevabot',
        'Nessus',
        'Net Vampire',
        'NetAnts',
        'Netcraft',
        'NetcraftSurveyAgent',
        'netEstate NE Crawler',
        'NetLyzer',
        'NetMechanic',
        'NetNewsWire',
        'NetSeer crawler',
        'NetSpider',
        'Nettrack',
        'Netvibes',
        'NetworkingExtension',
        'NetZIP',
        'newsblur',
        'newspaper',
        'NextGenSearchBot',
        'Nibbler',
        'NICErsPRO',
        'Niki-Bot',
        'Nikto',
        'NimbleCrawler',
        'Nimbostratus',
        'NING',
        'Ninja',
        'Nmap',
        'node-fetch',
        'NPbot',
        'Nuclei',
        'Nutch',
        'Nuzzel',
        'oBot',
        'Octopus',
        'Offline Explorer',
        'Offline Navigator',
        'okhttp',
        'omgili',
        'Omigili',
        'OnalyticaBot',
        'OnCrawl',
        'Openfind',
        'OpenLinkProfiler',
        'OpenVAS',
        'OrangeBot',
        'OrangeSpider',
        'OutclicksBot',
        'OutfoxBot',
        'ows.eu',
        'Page Analyzer',
        'page scorer',
        'PageAnalyzer',
        'PageGrabber',
        'PageScorer',
        'PageThing.com',
        'Pandalytics',
        'Panscient',
        'Papa Foto',
        'PaperLiBot',
        'Paqlebot',
        'Pavuk',
        'pcBrowser',
        'Pcore-HTTP',
        'PECL::HTTP',
        'PeoplePal',
        'PercolateCrawler',
        'petalsearch',
        'PHP-Curl-Class',
        'PHPCrawl',
        'PhxBot',
        'Pi-Monster',
        'Picscout',
        'Picsearch',
        'PictureFinder',
        'Piepmatz',
        'Pimonster',
        'Pingdom',
        'Pixray',
        'PleaseCrawl',
        'plumanalytics',
        'PocketParser',
        'Pockey',
        'POE-Component-Client-HTTP',
        'polaris version',
        'PrintfulBot',
        'probe-image-size',
        'Probethenet',
        'profound',
        'ProPowerBot',
        'protopage',
        'ProWebWalker',
        'proximic',
        'Psbot',
        'Pu_iN',
        'PulseCrawler',
        'Pump',
        'PxBroker',
        'PyCurl',
        'python-requests',
        'Python-urllib',
        'QueryN Metasearch',
        'QuerySeekerSpider',
        'Quick-Crawler',
        'Qwantbot',
        'Qwantify',
        'R6_CommentReader',
        'R6_FeedFetcher',
        'RankActive',
        'RankActiveLinkBot',
        'RankFlex',
        'RankingBot2',
        'RankingBot',
        'Rankivabot',
        'RankurBot',
        'Re-Animator Bot',
        'Re-re',
        'RealDownload',
        'Reaper',
        'RebelMouse',
        'Recorder',
        'RedesScrapy',
        'Reeder',
        'ReGet',
        'RepoLookoutBot',
        'RepoMonkey',
        'Ripper',
        'ripz',
        'RocketCrawler',
        'Rogerbot',
        'rogerbot-crawler',
        'rss-is-dead',
        'RSSingBot',
        's1z.ru',
        'SalesIntelligent',
        'satoristudio.net',
        'SBIder',
        'scalaj-http',
        'scan.lol',
        'ScanAlert',
        'Scanbot',
        'schmorp.de',
        'ScooperBot',
        'ScoutJet',
        'Scrapy',
        'Screaming',
        'ScreenerBot',
        'ScrepyBot',
        'Searchestate',
        'searchmetrics',
        'SearchmetricsBot',
        'Seekport Crawler',
        'Seekport',
        'Selfoss',
        'semantic-visions.com',
        'Semanticbot',
        'SemanticJuice',
        'SemanticScholarBot',
        'Semrush',
        'semrush.com',
        'SemrushBot',
        'SentiBot',
        'seobility',
        'SeobilityBot',
        'seocompany.store',
        'SEOkicks',
        'SEOlyticsCrawler',
        'Seomoz',
        'SEOprofiler',
        'seoscanners',
        'SeoSiteCheckup',
        'seostar',
        'SEOstats',
        'SerendeputyBot',
        'serpstatbot',
        'sexsearcher',
        'SeznamBot/3.2',
        'SeznamHomepage',
        'sfFeedReader',
        'ShapBot',
        'Shodan',
        'sindresorhus/got',
        'Siphon',
        'SISTRIX Crawler',
        'SISTRIX',
        'Site Sucker',
        'Sitebeam',
        'SiteCheck',
        'sitechecker.pro',
        'SiteCheckerBotCrawler',
        'SiteExplorer',
        'Siteimprove',
        'SiteLockSpider',
        'siteripz',
        'SiteSnagger',
        'SiteSucker',
        'Sitevigil',
        'SkyWatch',
        'Sleuth',
        'SlySearch',
        'SmartDownload',
        'SmartReader',
        'SMTBot',
        'SMXCrawler',
        'Snake',
        'Snapbot',
        'Snoopy',
        'SocialRankIOBot',
        'Sociscraper',
        'Sogou',
        'Sosospider',
        'Sottopop',
        'sp_auditbot',
        'SpaceBison',
        'SpaceCowboys',
        'Spammen',
        'SpankBot',
        'Spanner',
        'Spbot',
        'SpiderLing',
        'SpiderWeb',
        'spinn3r',
        'SputnikBot',
        'spyfu',
        'Sqlmap',
        'Sqlworm',
        'Sqworm',
        'Steeler',
        'StormCrawler',
        'StractBot',
        'Stripper',
        'Sucker',
        'Sucuri',
        'SummalyBot',
        'SuperBot',
        'superfeedr',
        'SuperHTTP',
        'Surfbot',
        'SurveyBot',
        'Suzuran',
        'Swiftbot',
        'Symfony BrowserKit',
        'sysomos.com',
        'sysscan',
        'Szukacz',
        'T0PHackTeam',
        'T8Abot',
        'tAkeOut',
        'techinfo@ubermetrics-technologies.com',
        'Teleport',
        'TeleportPro',
        'Telesoft',
        'Telesphoreo',
        'Telesphorep',
        'TencentTraveler',
        'TerraCotta',
        'terrykyleseoagency.com',
        'The Intraformant',
        'The Knowledge AI',
        'TheNomad',
        'Thumbor',
        'TightTwatBot',
        'TikTokSpider',
        'Timpibot',
        'TinEye-bot-live',
        'Tiny Tiny RSS',
        'Titan',
        'Toata',
        'Toweyabot',
        'Traackr.com',
        'Tracemyfile',
        'Trendiction',
        'trendiction.com',
        'trendiction.de',
        'Trendictionbot',
        'TrendsmapResolver',
        'True_Robot',
        'TTD-Content',
        'Turingos',
        'Turnitin',
        'TurnitinBot',
        'TweetedTimes Bot',
        'tweetedtimes',
        'TweetmemeBot',
        'TwengaBot',
        'Twice',
        'Twingly',
        'TwitterFeed',
        'Typhoeus',
        'ubermetrics',
        'ubermetrics-technologies.com',
        'UnisterBot',
        'UnwindFetchor',
        'updown_tester',
        'Upflow',
        'urlresolver',
        'URLy Warning',
        'URLy.Warning',
        'V-BOT',
        'Vacuum',
        'Vagabondo',
        'VB Project',
        'VCI',
        'VegeBot',
        'VelenPublicWebCrawler',
        'VelenPublicWebCrawler/1.0',
        'VeriCiteCrawler',
        'VidibleScraper',
        'Virusdie',
        'VoidEYE',
        'Voil',
        'Voltron',
        'voyagerx.com',
        'Wallpapers',
        'Wallpapers/3.0',
        'WallpapersHD',
        'WASALive-Bot',
        'WBSearchBot',
        'Web Auto',
        'Web Collage',
        'Web Enhancer',
        'Web Fetch',
        'Web Fuck',
        'Web Pix',
        'Web Sauger',
        'Web Sucker',
        'Webalta',
        'WebAuto',
        'WebBandit',
        'WebCollage',
        'WebCopier',
        'webdatastats.com',
        'WEBDAV',
        'WebEnhancer',
        'WebFetch',
        'WebFuck',
        'webgains-bot',
        'WebGo IS',
        'WebImageCollector',
        'WebLeacher',
        'WebmasterWorldForumBot',
        'webmeup-crawler',
        'WebPix',
        'webpros.com',
        'webprosbot',
        'WebReaper',
        'WebSauger',
        'Webshag',
        'Website Quester',
        'WebsiteExtractor',
        'WebsiteQuester',
        'Webster',
        'WebStripper',
        'WebSucker',
        'WebWhacker',
        'WebZIP',
        'WellKnownBot',
        'WeSEE',
        'Whack',
        'Whacker',
        'Whatweb',
        'Who.is Bot',
        'Widow',
        'Winds: Open Source RSS & Podcast',
        'WinHTTrack',
        'WiseGuys Robot',
        'WISENutbot',
        'Wonderbot',
        'Woobot',
        'WordPress.com mShots',
        'woriobot',
        'Wotbox',
        'wp_is_mobile',
        'WPMU DEV',
        'Wprecon',
        'WPScan',
        'WWW-Collector-E',
        'WWW-Mechanize',
        'WWW::Mechanize',
        'WWWOFFLE',
        'x09Mozilla',
        'x22Mozilla',
        'Xaldon WebSpider',
        'Xaldon_WebSpider',
        'XenForo',
        'Xenu',
        'XoviBot',
        'xpymep1.exe',
        'Y!J-BRW',
        'yacybot',
        'Yahoo Ad monitoring',
        'Yahoo! Slurp',
        'YaK/1.0',
        'YoudaoBot',
        'Zade',
        'Zauba',
        'zauba.io',
        'Zermelo',
        'Zeus',
        'zgrab',
        'Zitebot',
        'ZmEu',
        'Zombiebot',
        'ZoomBot',
        'ZoominfoBot',
        'ZumBot',
        'ZyBorg',
        'Node.js',
        'Deno',
        'insomnia',
        'CCBot/2',
        'omgilibot',
        'Omgilibot',
        'YouBot',
        'AI2Bot',
        'cohere-training-data-crawler',
        'Kangaroo Bot',
        'Scrapy/2',
        'ZoomInfo',
        'peer39_crawler',
        'Sidetrade indexer bot',
        'Bytedance',
        'ImageSiftBot',
        'YouBotAI',
        'meta-externalfetcher',
        'DuckAssistBot',
        'GoogleAgent-Mariner',
        'Ai2Bot-Dolma',
        'UptimeRobot',
        'StatusCake',
        'Better Uptime',
        'freshping',
        'Site24x7',
        'NewRelicPinger',
        'Datadog Synthetics',
        'GTmetrix',
        'PageSpeed',
        'Lighthouse',
        'WebPageTest',
        'Checkly',
        'Uptime.com',
        'Pingometer',
        'HetrixTools',
        'Montastic',
        'Panopta',
    ];
    /**
     * Main entry point.
     *
     * @param bool $logs Whether to log detected bots to a CSV log.
     * @param bool $checkHoneypot Whether to check the self::HONEYPOT_FIELD_NAME field in $_POST.
     * @param bool $checkDns Whether to verify known bots (Googlebot, etc.) via reverse-DNS.
     *                       Disable on very high-traffic sites if the cost of DNS queries
     *                       would be too high despite caching.
     * @param bool $checkBehavior Whether to analyze request frequency over time (requires
     *                            per-IP disk writes; disable if undesirable under heavy traffic).
     */
    public static function detect(
        bool $logs = false,
        bool $checkHoneypot = true,
        bool $checkDns = true,
        bool $checkBehavior = true
    ): bool {
        $headers = self::currentRequestHeaders();
        $userAgent = $_SERVER['HTTP_USER_AGENT'] ?? '';
        $honeypotTriggered = $checkHoneypot && self::honeypotTriggered();
        $result = self::analyze(
            $userAgent,
            $headers,
            null,
            $honeypotTriggered,
            $checkDns,
            $checkBehavior
        );
        if ($result['is_bot'] && $logs) {
            self::writeLogLine($result, $userAgent, $headers, self::logDirectory());
        }
        return $result['is_bot'];
    }
    private static function writeLogLine(array $result, string $userAgent, array $headers, string $logDirectory): void
    {
        $normalizedHeaders = [];
        foreach ($headers as $key => $value) {
            $normalizedHeaders[strtolower((string) $key)] = (string) $value;
        }
        $matchedSignature = null;
        foreach ($result['signals'] as $signal) {
            if (str_starts_with($signal, 'ua_signature_match:')) {
                $matchedSignature = substr($signal, strlen('ua_signature_match:'));
                break;
            }
        }
        $now = new DateTimeImmutable('now');
        $verified = $result['verified'] ?? null;
        $verifiedLabel = $verified === null ? '' : ($verified ? '1' : '0');
        $row = [
            $now->format(DATE_ATOM),
            self::resolveClientIp($normalizedHeaders),
            '1',
            $result['category'] ?? '',
            number_format($result['score'], 2, '.', ''),
            number_format($result['confidence'], 2, '.', ''),
            $verifiedLabel,
            $matchedSignature ?? '',
            $userAgent,
            self::currentRequestUri(),
            $_SERVER['REQUEST_METHOD'] ?? '',
            $normalizedHeaders['referer'] ?? '',
            implode(' ', $result['signals']),
        ];
        $line = self::csvRow($row);
        $filePath = rtrim($logDirectory, '/\\') . '/' . $now->format('Y-m-d') . '.csv';
        if (!is_dir($logDirectory)) {
            @mkdir($logDirectory, 0775, true);
        }
        if (!file_exists($filePath)) {
            $csvHeaders = [
                'timestamp',
                'client_ip',
                'flag',
                'category',
                'score',
                'confidence',
                'verified',
                'matched_signature',
                'user_agent',
                'request_uri',
                'request_method',
                'referer',
                'signals'
            ];
            $line = self::csvRow($csvHeaders) . $line;
        }
        file_put_contents($filePath, $line, FILE_APPEND | LOCK_EX);
    }
    private static function csvRow(array $fields): string
    {
        $escaped = array_map(static function (string $field): string {
            $field = str_replace(["\r\n", "\r", "\n"], ' ', $field);
            if (str_contains($field, ',') || str_contains($field, '"')) {
                return '"' . str_replace('"', '""', $field) . '"';
            }
            return $field;
        }, $fields);
        return implode(',', $escaped) . "\n";
    }
    private static function resolveClientIp(array $normalizedHeaders): string
    {
        if (!empty($normalizedHeaders['cf-connecting-ip'])) {
            return trim($normalizedHeaders['cf-connecting-ip']);
        }
        if (!empty($normalizedHeaders['x-forwarded-for'])) {
            $parts = explode(',', $normalizedHeaders['x-forwarded-for']);
            $first = trim($parts[0]);
            if ($first !== '') {
                return $first;
            }
        }
        return $_SERVER['REMOTE_ADDR'] ?? '';
    }
    private static function currentRequestUri(): string
    {
        return $_SERVER['REQUEST_URI'] ?? '';
    }
    private static function analyze(
        ?string $userAgent = null,
        ?array $headers = null,
        ?string $clientIp = null,
        bool $honeypotTriggered = false,
        bool $checkDns = true,
        bool $checkBehavior = true
    ): array {
        $userAgentExplicitlyEmpty = $userAgent === '';
        $userAgent = $userAgent ?? ($_SERVER['HTTP_USER_AGENT'] ?? '');
        $headersWereExplicitlyProvided = $headers !== null;
        $headers = $headers ?? self::currentRequestHeaders();
        $normalizedHeaders = [];
        foreach ($headers as $key => $value) {
            $normalizedHeaders[strtolower((string) $key)] = (string) $value;
        }
        $clientIp = $clientIp ?? self::resolveClientIp($normalizedHeaders);
        $uaMatch = self::matchUserAgent($userAgent);
        $headerScore = self::analyzeHeaders($headers, $userAgent);
        $signals = [];

        if ($userAgent === '' && $userAgentExplicitlyEmpty === false && !isset($_SERVER['HTTP_USER_AGENT'])) {
            $signals[] = 'no_user_agent_available';
        }

        // Honeypot: an absolutely decisive signal — no human fills in a hidden field.
        if ($honeypotTriggered) {
            $signals[] = 'honeypot_field_filled';
            return [
                'is_bot' => true,
                'confidence' => 1.0,
                'category' => self::CATEGORY_HONEYPOT_TRIGGER,
                'score' => 1.0,
                'verified' => true,
                'signals' => $signals,
            ];
        }

        if ($uaMatch !== null) {
            $signals[] = "ua_signature_match:{$uaMatch['signature']}";

            // For search engine bots with an rDNS rule: check whether the IP actually
            // belongs to the declared company. If the UA is spoofed (e.g. "Googlebot"
            // sent from a VPS server), we treat it as spoofing, not a legitimate bot.
            if ($checkDns && $uaMatch['category'] === self::CATEGORY_SEARCH_ENGINE && $uaMatch['engine'] !== null) {
                $verified = self::verifyKnownBotByDns($uaMatch['engine'], $clientIp);
                if ($verified === false) {
                    $signals[] = 'ua_claims_known_bot_but_dns_verification_failed';
                    return [
                        'is_bot' => true,
                        'confidence' => 0.97,
                        'category' => self::CATEGORY_SPOOFED_BOT,
                        'score' => 1.0,
                        'verified' => false,
                        'signals' => $signals,
                    ];
                }
                if ($verified === true) {
                    $signals[] = 'dns_verified_known_bot';
                }
            }

            return [
                'is_bot' => true,
                'confidence' => 0.9,
                'category' => $uaMatch['category'],
                'score' => 1.0,
                'verified' => $checkDns ? (self::verifyKnownBotByDns($uaMatch['engine'] ?? '', $clientIp) === true) : null,
                'signals' => $signals,
            ];
        }

        if (!$headersWereExplicitlyProvided && $headers === []) {
            $signals[] = 'no_headers_available_header_analysis_skipped';
            $score = 0.0;
        } else {
            $score = $headerScore['score'] * self::HEADER_ANALYSIS_WEIGHT;
            foreach ($headerScore['signals'] as $signal) {
                $signals[] = "header:{$signal}";
            }
        }

        // A UA-independent signal: an IP belonging to a known data center / cloud.
        // Not decisive on its own (legitimate traffic can come from there too),
        // but combined with suspicious headers it significantly raises confidence.
        if (self::isDataCenterIp($clientIp)) {
            $signals[] = 'client_ip_in_datacenter_range';
            $score += 0.30;
        }

        // Timing analysis: consecutive requests from the same IP arriving too fast.
        if ($checkBehavior) {
            $timing = self::analyzeRequestTiming($clientIp);
            foreach ($timing['signals'] as $signal) {
                $signals[] = "behavior:{$signal}";
            }
            $score += $timing['score'];
        }

        $score = min(1.0, $score);
        $isBot = $score >= self::BOT_THRESHOLD;
        return [
            'is_bot' => $isBot,
            'confidence' => $score,
            'category' => $isBot ? self::CATEGORY_UNKNOWN_BOT : null,
            'score' => $score,
            'verified' => null,
            'signals' => $signals,
        ];
    }
    /**
     * Checks whether the given IP belongs to a known data center / cloud range.
     * Works independently of the User-Agent — detects bots even when they
     * impersonate a browser, as long as they connect from a server rather
     * than a home connection.
     */
    private static function isDataCenterIp(string $ip): bool
    {
        if ($ip === '' || !filter_var($ip, FILTER_VALIDATE_IP)) {
            return false;
        }
        if (str_contains($ip, ':')) {
            return false; // IPv6 skipped — the CIDR list only covers IPv4
        }
        foreach (self::$dataCenterCidrRanges as $cidr) {
            if (self::ipInCidr($ip, $cidr)) {
                return true;
            }
        }
        return false;
    }

    private static function ipInCidr(string $ip, string $cidr): bool
    {
        [$subnet, $maskBits] = array_pad(explode('/', $cidr, 2), 2, '32');
        $maskBits = (int) $maskBits;
        $ipLong = ip2long($ip);
        $subnetLong = ip2long($subnet);
        if ($ipLong === false || $subnetLong === false) {
            return false;
        }
        if ($maskBits <= 0) {
            return true;
        }
        if ($maskBits >= 32) {
            return $ipLong === $subnetLong;
        }
        $mask = -1 << (32 - $maskBits);
        return ($ipLong & $mask) === ($subnetLong & $mask);
    }

    /**
     * Verifies via reverse/forward DNS whether a bot declaring itself as
     * e.g. Googlebot actually connects from the given provider's network.
     * The result is cached on disk (TTL) to avoid running costly DNS
     * queries on every request.
     *
     * @return bool|null true = verified, false = spoofing/mismatch, null = no rule / not checked
     */
    private static function verifyKnownBotByDns(string $engine, string $ip): ?bool
    {
        if (!isset(self::$trustedReverseDnsSuffixes[$engine]) || $ip === '' || !filter_var($ip, FILTER_VALIDATE_IP)) {
            return null;
        }
        $cacheKey = $engine . ':' . $ip;
        $cached = self::readDnsVerificationCache($cacheKey);
        if ($cached !== null) {
            return $cached;
        }
        $ptr = @gethostbyaddr($ip);
        if ($ptr === false || $ptr === $ip) {
            self::writeDnsVerificationCache($cacheKey, false);
            return false;
        }
        $ptrLower = strtolower(rtrim($ptr, '.'));
        $suffixMatched = false;
        foreach (self::$trustedReverseDnsSuffixes[$engine] as $suffix) {
            if (str_ends_with($ptrLower, ltrim($suffix, '.')) || str_ends_with('.' . $ptrLower, $suffix)) {
                $suffixMatched = true;
                break;
            }
        }
        if (!$suffixMatched) {
            self::writeDnsVerificationCache($cacheKey, false);
            return false;
        }
        // Bidirectional verification: forward-resolve the PTR and compare it to the original IP
        $forward = @gethostbynamel($ptrLower);
        $verified = is_array($forward) && in_array($ip, $forward, true);
        self::writeDnsVerificationCache($cacheKey, $verified);
        return $verified;
    }

    private static function readDnsVerificationCache(string $key): ?bool
    {
        $file = self::dnsCacheFilePath($key);
        if (!is_file($file)) {
            return null;
        }
        $raw = @file_get_contents($file);
        if ($raw === false) {
            return null;
        }
        $data = json_decode($raw, true);
        if (!is_array($data) || !isset($data['expires'], $data['verified'])) {
            return null;
        }
        if ($data['expires'] < time()) {
            return null;
        }
        return (bool) $data['verified'];
    }

    private static function writeDnsVerificationCache(string $key, bool $verified): void
    {
        $dir = self::dnsCacheDirectory();
        if (!is_dir($dir)) {
            @mkdir($dir, 0775, true);
        }
        $file = self::dnsCacheFilePath($key);
        $payload = json_encode(['verified' => $verified, 'expires' => time() + self::DNS_VERIFY_CACHE_TTL]);
        if ($payload !== false) {
            @file_put_contents($file, $payload, LOCK_EX);
        }
    }

    private static function dnsCacheFilePath(string $key): string
    {
        return self::dnsCacheDirectory() . '/' . sha1($key) . '.json';
    }

    /**
     * Returns true if the honeypot field (hidden from humans via CSS,
     * but visible to simple bots that fill in every input) was filled in.
     * The form should contain a field named self::HONEYPOT_FIELD_NAME,
     * hidden e.g. via `position:absolute; left:-9999px` (NOT display:none,
     * since some bots skip fields hidden with display:none/hidden).
     */
    public static function honeypotTriggered(?array $requestData = null): bool
    {
        $data = $requestData ?? $_POST;
        $value = $data[self::HONEYPOT_FIELD_NAME] ?? '';
        return is_string($value) ? trim($value) !== '' : $value !== null && $value !== '';
    }

    /**
     * Behavioral analysis based on a series of requests from the same IP within
     * a short time window: a request frequency too high (below the minimum
     * human reaction time) is a strong signal of automation. State is kept in
     * cache files on disk, keyed by IP, with a short TTL.
     */
    private static function analyzeRequestTiming(string $ip): array
    {
        $signals = [];
        $score = 0.0;
        if ($ip === '') {
            return ['score' => 0.0, 'signals' => $signals];
        }
        $dir = self::behaviorStateDirectory();
        if (!is_dir($dir)) {
            @mkdir($dir, 0775, true);
        }
        $file = rtrim($dir, '/\\') . '/' . sha1($ip) . '.json';
        $now = microtime(true);
        $state = null;
        if (is_file($file)) {
            $raw = @file_get_contents($file);
            $decoded = $raw !== false ? json_decode($raw, true) : null;
            if (is_array($decoded) && isset($decoded['last_request'], $decoded['count'])) {
                $state = $decoded;
            }
        }
        if ($state !== null && ($now - (float) $state['last_request']) < self::BEHAVIOR_STATE_TTL) {
            $delta = $now - (float) $state['last_request'];
            if ($delta < self::BEHAVIOR_MIN_INTERVAL_SECONDS) {
                $signals[] = 'requests_faster_than_human_interval';
                $score += 0.30;
            }
            $newCount = min((int) $state['count'] + 1, 1000000);
            if ($newCount >= 20 && $delta < 2.0) {
                $signals[] = 'sustained_high_frequency_requests';
                $score += 0.20;
            }
            $payload = ['last_request' => $now, 'count' => $newCount];
        } else {
            $payload = ['last_request' => $now, 'count' => 1];
        }
        $encoded = json_encode($payload);
        if ($encoded !== false) {
            @file_put_contents($file, $encoded, LOCK_EX);
        }
        return ['score' => min(1.0, $score), 'signals' => $signals];
    }

    private static function matchUserAgent(string $userAgent): ?array
    {
        $userAgent = trim($userAgent);
        if ($userAgent === '') {
            return null;
        }
        $lowerUa = strtolower($userAgent);
        foreach (self::$searchEngineBots as $signature => $engine) {
            if (self::signatureMatches($signature, $lowerUa)) {
                return ['signature' => $signature, 'category' => self::CATEGORY_SEARCH_ENGINE, 'engine' => $engine];
            }
        }
        foreach (self::$socialMediaBots as $signature) {
            if (self::signatureMatches($signature, $lowerUa)) {
                return ['signature' => $signature, 'category' => self::CATEGORY_SOCIAL_MEDIA, 'engine' => null];
            }
        }
        foreach (self::$securityToolMarkers as $marker) {
            if (self::signatureMatches($marker, $lowerUa)) {
                return ['signature' => $marker, 'category' => self::CATEGORY_SECURITY_TOOL, 'engine' => null];
            }
        }
        foreach (self::$headlessBrowserMarkers as $marker) {
            if (self::signatureMatches($marker, $lowerUa)) {
                return ['signature' => $marker, 'category' => self::CATEGORY_HEADLESS_BROWSER, 'engine' => null];
            }
        }
        foreach (self::$httpLibraryMarkers as $marker) {
            if (self::signatureMatches($marker, $lowerUa)) {
                return ['signature' => $marker, 'category' => self::CATEGORY_HTTP_LIBRARY, 'engine' => null];
            }
        }
        foreach (self::$miscBots as $signature) {
            if (self::signatureMatches($signature, $lowerUa)) {
                return ['signature' => $signature, 'category' => self::CATEGORY_SCRAPER, 'engine' => null];
            }
        }
        return null;
    }
    private const SHORT_SIGNATURE_LENGTH_THRESHOLD = 6;
    private static function signatureMatches(string $signature, string $lowerHaystack): bool
    {
        $lowerSignature = strtolower($signature);
        if (strlen($lowerSignature) > self::SHORT_SIGNATURE_LENGTH_THRESHOLD) {
            return str_contains($lowerHaystack, $lowerSignature);
        }
        $pos = strpos($lowerHaystack, $lowerSignature);
        if ($pos === false) {
            return false;
        }
        $signatureStartsAlnum = ctype_alnum($lowerSignature[0]);
        $signatureEndsAlnum = ctype_alnum($lowerSignature[strlen($lowerSignature) - 1]);
        if ($signatureStartsAlnum) {
            $before = $pos > 0 ? $lowerHaystack[$pos - 1] : null;
            if ($before !== null && ctype_alnum($before)) {
                return false;
            }
        }
        if ($signatureEndsAlnum) {
            $afterPos = $pos + strlen($lowerSignature);
            $after = $afterPos < strlen($lowerHaystack) ? $lowerHaystack[$afterPos] : null;
            if ($after !== null && ctype_alnum($after)) {
                return false;
            }
        }
        return true;
    }
    private static function analyzeHeaders(array $headers, string $userAgent = ''): array
    {
        $normalized = [];
        foreach ($headers as $key => $value) {
            $normalized[strtolower((string) $key)] = (string) $value;
        }
        $effectiveUa = $userAgent !== '' ? $userAgent : ($normalized['user-agent'] ?? '');
        $lowerUa = strtolower($effectiveUa);
        $signals = [];
        $score = 0.0;
        if (!isset($normalized['accept']) || $normalized['accept'] === '') {
            $signals[] = 'missing_accept_header';
            $score += 0.25;
        } elseif (trim($normalized['accept']) === '*/*') {
            $signals[] = 'generic_accept_header';
            $score += 0.10;
        }
        if (!isset($normalized['accept-language']) || $normalized['accept-language'] === '') {
            $signals[] = 'missing_accept_language';
            $score += 0.20;
        } elseif (!preg_match('/^[a-zA-Z*]{1,8}([-;,=.\d a-zA-Z*])*$/', trim($normalized['accept-language']))) {
            $signals[] = 'malformed_accept_language';
            $score += 0.20;
        }
        if (!isset($normalized['accept-encoding']) || $normalized['accept-encoding'] === '') {
            $signals[] = 'missing_accept_encoding';
            $score += 0.15;
        }
        $uaClaimsChromium = str_contains($effectiveUa, 'Chrome/') || str_contains($effectiveUa, 'Edg/');
        $uaClaimsFirefox = str_contains($effectiveUa, 'Firefox/') && !str_contains($effectiveUa, 'Seamonkey/');
        $uaClaimsSafari = str_contains($effectiveUa, 'Safari/') && !$uaClaimsChromium;
        $uaClaimsModernBrowser = $uaClaimsChromium || $uaClaimsFirefox || $uaClaimsSafari;
        if ($uaClaimsChromium) {
            $hasSecFetch = isset($normalized['sec-fetch-mode']) || isset($normalized['sec-fetch-site']);
            $hasClientHints = isset($normalized['sec-ch-ua']);
            if (!$hasSecFetch && !$hasClientHints) {
                $signals[] = 'chromium_ua_without_sec_headers';
                $score += 0.35;
            }
        }
        if (
            isset($normalized['x-requested-with'])
            && str_contains(strtolower($normalized['x-requested-with']), 'headlesschrome')
        ) {
            $signals[] = 'headless_chrome_marker';
            $score += 0.40;
        }
        if (!isset($normalized['host']) || $normalized['host'] === '') {
            $signals[] = 'missing_host_header';
            $score += 0.15;
        }
        if (isset($normalized['sec-ch-ua-platform']) && $normalized['sec-ch-ua-platform'] !== '') {
            $declaredPlatform = strtolower(trim($normalized['sec-ch-ua-platform'], "\" \t\n\r"));
            $uaSaysWindows = str_contains($lowerUa, 'windows');
            $uaSaysMac = str_contains($lowerUa, 'macintosh') || str_contains($lowerUa, 'mac os');
            $uaSaysLinux = str_contains($lowerUa, 'linux') && !str_contains($lowerUa, 'android');
            $uaSaysAndroid = str_contains($lowerUa, 'android');
            $platformMismatch =
                ($declaredPlatform === 'windows' && !$uaSaysWindows)
                || ($declaredPlatform === 'macos' && !$uaSaysMac)
                || ($declaredPlatform === 'android' && !$uaSaysAndroid)
                || ($declaredPlatform === 'linux' && !$uaSaysLinux && !$uaSaysAndroid);
            if ($platformMismatch) {
                $signals[] = 'ua_platform_client_hint_mismatch';
                $score += 0.35;
            }
        }
        if (isset($normalized['sec-fetch-mode']) && $normalized['sec-fetch-mode'] === 'navigate') {
            $dest = strtolower($normalized['sec-fetch-dest'] ?? '');
            if ($dest !== '' && $dest !== 'document' && $dest !== 'iframe' && $dest !== 'frame') {
                $signals[] = 'inconsistent_sec_fetch_navigate_dest';
                $score += 0.25;
            }
        }
        if (
            $uaClaimsModernBrowser
            && isset($normalized['connection'])
            && strtolower(trim($normalized['connection'])) === 'close'
        ) {
            $signals[] = 'modern_browser_ua_with_connection_close';
            $score += 0.15;
        }
        foreach (self::$cloudHostingMarkers as $marker) {
            if ($lowerUa !== '' && str_contains($lowerUa, $marker)) {
                $signals[] = 'cloud_hosting_marker_in_ua';
                $score += 0.30;
                break;
            }
        }
        if ($effectiveUa !== '') {
            $uaLength = strlen($effectiveUa);
            if ($uaLength < 15) {
                $signals[] = 'implausibly_short_user_agent';
                $score += 0.20;
            } elseif ($uaLength > 400) {
                $signals[] = 'implausibly_long_user_agent';
                $score += 0.15;
            }
        }
        $hasPrivacyHeader = isset($normalized['dnt']) || isset($normalized['sec-gpc']);
        $hasAnyBrowserFingerprint = isset($normalized['sec-fetch-mode'])
            || isset($normalized['sec-ch-ua'])
            || isset($normalized['accept-language']);
        if ($hasPrivacyHeader && !$hasAnyBrowserFingerprint) {
            $signals[] = 'privacy_header_without_browser_fingerprint';
            $score += 0.10;
        }
        return ['score' => min(1.0, $score), 'signals' => $signals];
    }
    private static function currentRequestHeaders(): array
    {
        if (function_exists('getallheaders')) {
            $headers = getallheaders();
            if ($headers !== false) {
                return $headers;
            }
        }
        $headers = [];
        foreach ($_SERVER as $key => $value) {
            if (str_starts_with($key, 'HTTP_')) {
                $headerName = str_replace(' ', '-', ucwords(str_replace('_', ' ', strtolower(substr($key, 5)))));
                $headers[$headerName] = $value;
            }
        }
        return $headers;
    }
}