<?php
// config/bb_config.php
return [
    'preset'     => 'minimal',
    'strictness' => 'monitor-only',  // start safe, ramp up later
    'logging'    => true,
];

<?php
return [
    // Required-ish
    'preset'         => 'minimal',
    'strictness'     => 'monitor-only',
    'logging'        => true,

    // Behind Cloudflare (set true + add CF ranges)
    'reverse_proxy'  => [
        'enabled'   => true,
        'header'    => 'CF-Connecting-IP',
        'addresses' => [
            '173.245.48.0/20',
            '103.21.244.0/22',
            // ... (all CF ranges)
        ],
    ],

    // Custom category overrides
    'bot_categories' => [
        'blocked'   => ['residential_proxy'],
        'challenge' => ['ai_crawler'],
        'log_only'  => ['security_scanner'],
        'allowed'   => ['feed_reader'],
    ],

    // See also: custom_rules for per-bot or per-IP rules
    'custom_rules'   => [
        ['type' => 'ip', 'value' => '203.0.113.0/24', 'action' => 'block'],
    ],
];

$ php bin/diagnose.php

1. CONFIG_DIR/bb_config.php    (if CONFIG_DIR constant defined — WackoWiki)
2. config/bb_config.php        (CWD-relative — CLI tools)
3. <package_root>/config/bb_config.php   (most installations)		

defaults         ←  Configuration::get_defaults()
    ↓
strictness layer ←  Configuration::strictness_overrides($strictness)
    ↓
user config      ←  YOUR bb_config.php
    ↓
final config     ←  Configuration::from_array() result		

return [
    'strictness' => 'normal',
    'dns_verification' => ['enabled' => false],   // overrides 'normal' default
];

if ($bb->is_in_safe_mode()) {
    // Config file missing or invalid — operator needs to fix it
}

$config = Configuration::from_array([
    'preset'     => 'minimal',
    'strictness' => 'monitor-only',
    'logging'    => true,
], $adapter);

// Read properties:
echo $config->strictness;            // 'monitor-only'
echo $config->log_table;             // 'bad_behaviour' (injected by adapter)
echo $config->dns_verification_enabled;  // false (monitor-only override)

// Round-trip back to array:
$array = $config->to_array();

// Inject into BadBehaviour:
$bb = new BadBehaviour($config);

return [
    'strictness' => 'monitor-only',  // or 'normal' or 'strict'
];

return [
    'strictness' => 'monitor-only',
    'rate_limit_enabled' => true,           // ← enable rate limits but keep monitor-only demotion
    'enable_behavioral_analysis' => true,   // ← see behavioral patterns in logs without enforcing
];

return [
    'strictness' => 'strict',
    'block_unverified_ai' => false,   // ← AI crawlers logged not blocked even at strict
];

return [
    'bot_categories' => [
        'blocked'   => [],   // hard-block by category
        'challenge' => [],   // force CAPTCHA by category
        'log_only'  => [],   // log but never block
        'allowed'   => [],   // allow verified-by-default categories
    ],
];

blocked[]   >  challenge[]  >  log_only[]  >  allowed[]		

'bot_categories' => [
    'blocked' => ['residential_proxy'],
],

'bot_categories' => [
    'challenge' => ['social_crawler'],
],

'bot_categories' => [
    'log_only' => ['security_scanner'],
],

'bot_categories' => [
    'allowed' => ['feed_reader', 'archive_crawler'],
],

'bot_categories' => [
    'blocked'   => ['residential_proxy'],
    'challenge' => ['ai_crawler'],          // challenge ALL AI crawlers
    'log_only'  => ['security_scanner'],
    'allowed'   => ['feed_reader'],
],

'bot_categories' => ['challenge' => ['ai_crawler']]

return [
    'preset' => 'minimal',  // default
];

return [
    'preset'             => 'minimal',

    // Drop whole categories
    'exclude_categories' => ['seo_crawler', 'shopping_crawler'],

    // Re-add categories (overrides exclude). CRITICAL for cloud_infrastructure.
    'include_categories' => ['cloud_infrastructure'],

    // Drop specific bots by ID
    'exclude_bots'       => ['petal'],

    // Add custom bots on top
    'additions'          => [
        'my_internal_bot' => [
            'name'                => 'My Internal Crawler',
            'user_agent_patterns' => ['MyBot', 'MyBot/1.0'],
            'category'            => 'monitoring',
            'ip_ranges'           => ['10.0.0.0/8'],
            'default_action'      => 'allow',
        ],
    ],
];

return [
    'preset' => 'human-only',
    'include_categories' => ['cloud_infrastructure'],  // ← safety net
    'additions' => [
        'your_bot' => [...],
    ],
];

'additions' => [
    'my_bot' => [
        // Required
        'name'                => 'Human-readable bot name',
        'user_agent_patterns' => ['MyBot', 'MyBot/1.0'],   // ≥1 pattern, ≥3 chars each
        'category'            => 'search_engine',           // see category list above

        // Optional
        'host_patterns'       => ['bot.example.com'],
        'ip_ranges'           => ['192.0.2.0/24', '2001:db8::/32'],
        'verify_dns'          => true,
        'dns_suffixes'        => ['bot.example.com'],
        'robots_txt_token'    => 'MyBot',
        'default_action'      => 'allow',                    // allow|challenge|block|log_only
        'description'         => 'What this bot does',
    ],
],

'logging' => true,   // default

'verbose' => true,

status_code              enforcement_action   original_code             meaning
monitored.bot            monitored            blocked.bot               Would have blocked, didn't
monitored.malicious_ua   monitored            blocked.malicious_ua      Would have blocked, didn't
blocked.malicious_ua     enforced             NULL                      Empty UA, actually 403'd
blocked.attack_pattern   enforced             NULL                      Raw XSS, actually 403'd
allowed                  allowed              NULL                      Normal request (verbose=true only)		

KEY idx_ip          (ip)
KEY idx_status      (status_code)
KEY idx_date        (date)
KEY idx_bot         (bot_category, bot_verified)
KEY idx_enforcement (enforcement_action, date)   -- monitor-only queries

-- 1. Is monitor-only actually working?
SELECT enforcement_action, COUNT(*) AS n
FROM bad_behaviour
WHERE date >= CURDATE()
GROUP BY enforcement_action;

-- Expected (monitor-only):
--   enforced   ~0-20       (only empty UA + raw XSS)
--   monitored  ~50-5000    (bots, attacks, rate limits)
--   allowed    0           (set verbose=true if you want these)

-- 2. What would have been blocked if I'd been at 'normal' strictness?
SELECT status_code, COUNT(*) AS n
FROM bad_behaviour
WHERE enforcement_action = 'monitored'
  AND date >= CURDATE()
GROUP BY status_code
ORDER BY n DESC;

-- 3. Top offenders
SELECT ip, COUNT(*) AS hits, MIN(date) AS first_seen
FROM bad_behaviour
WHERE enforcement_action = 'monitored'
  AND date >= NOW() - INTERVAL 7 DAY
GROUP BY ip
ORDER BY hits DESC
LIMIT 20;

-- 4. Bot category breakdown
SELECT
    JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.bot_category')) AS bot_category,
    COUNT(*) AS n
FROM bad_behaviour
WHERE metadata LIKE '%bot_category%'
  AND date >= CURDATE()
GROUP BY bot_category
ORDER BY n DESC;

'rate_limits' => [
    'enabled'     => true,

    // All requests per IP per hour
    'global'      => ['requests' => 1000, 'window' => 3600],

    // Burst protection per IP per minute
    'per_minute'  => ['requests' => 60,   'window' => 60],

    // Form submissions per IP per hour
    'post'        => ['requests' => 30,   'window' => 3600],

    // Login attempts per IP per 15 minutes (credential stuffing)
    'login'       => ['requests' => 10,   'window' => 900],
],

'rate_limits' => [
    'global'     => ['requests' => 5000, 'window' => 3600],   // 5x headroom
    'per_minute' => ['requests' => 300,  'window' => 60],     // 5x headroom
],

-- What are realistic request rates per legitimate IP?
SELECT
    ip,
    COUNT(*) AS requests_per_hour,
    COUNT(DISTINCT DATE_FORMAT(date, '%Y-%m-%d %H:00:00')) AS hours_active,
    COUNT(*) / NULLIF(COUNT(DISTINCT DATE_FORMAT(date, '%Y-%m-%d %H:00:00')), 0) AS avg_per_hour
FROM bad_behaviour
WHERE enforcement_action = 'allowed'
  AND date >= NOW() - INTERVAL 7 DAY
GROUP BY ip
HAVING requests_per_hour > 100
ORDER BY requests_per_hour DESC
LIMIT 50;

'custom_rules' => [
    [
        'type'    => 'header',
        'header'  => 'X-Login-Path',
        'value'   => 'yes',
        'action'  => 'challenge',
    ],
],

'dns_verification' => [
    'enabled'                  => true,
    'timeout_ms'               => 300,
    'require_forward_confirm'  => false,
    'positive_ttl'             => 604800,    // 7 days
    'negative_ttl'             => 3600,      // 1 hour
],

1. Bot UA claims "Googlebot"
2. Library checks IP against static Google ranges
3. If no static match: reverse-DNS lookup (PTR record)
4. Result: "crawl-1-2-3.googlebot.com"
5. Check suffix matches "googlebot.com"
6. If yes → ALLOW (cached for positive_ttl seconds)
7. If no → CHALLENGE or BLOCK depending on config		

'dns_verification' => [
    'require_forward_confirm' => true,   // turn on if you're seeing PTR spoofers
],

'ai_crawlers' => [
    'allowed'          => ['GPTBot', 'ClaudeBot', 'Google-Extended'],
    'block_unverified' => false,
    'strict'           => false,
],

'allowed' => [
    'GPTBot',                  // OpenAI
    'ChatGPT-User',            // OpenAI on-demand
    'OAI-SearchBot',           // OpenAI search
    'ClaudeBot',               // Anthropic
    'Claude-Web',              // Anthropic search
    'Google-Extended',         // Google AI training
    'PerplexityBot',           // Perplexity
    'GrokBot',                 // xAI
    'MistralBot',              // Mistral
    'YouBot',                  // You.com
    'Meta-ExternalAgent',      // Meta AI
],

User-agent: GPTBot
Disallow: /

User-agent: ClaudeBot
Disallow: /

User-agent: Google-Extended
Disallow: /		

'dnsbl' => [
    'enabled' => true,
    'lists'   => ['zen.spamhaus.org', 'bl.spamcop.net'],
],

'httpbl' => [
    'key'     => 'your-access-key',  // from https://www.projecthoneypot.org/
    'threat'  => 25,                 // minimum threat score (0-255)
    'maxage'  => 30,                 // max days since last activity
],

'enable_fingerprinting' => true,
'fingerprints' => [
    'bad_ja3'           => ['e7d705a3286e19ea42f587b344ee6865'],
    'bad_h2'            => ['a1b2c3d4e5f6...'],
    'bot_header_orders' => ['...'],
    'expected_ja3'      => ['chrome-ja3-here'],
],

'geoip' => [
    'enabled'             => true,
    'database_path'       => '/usr/share/GeoIP/GeoLite2-Country.mmdb',
    'blocked_countries'   => ['CN', 'RU'],
    'blocked_asns'        => ['AS15169'],   // Google
],

'challenge' => [
    'enabled'             => true,
    'provider'            => 'turnstile',   // builtin | recaptcha | hcaptcha | turnstile
    'site_key'            => 'your-site-key',
    'secret_key'          => 'your-secret-key',
    'recaptcha_min_score' => 0.5,           // reCAPTCHA v3 only
],

// Per-rule, not library-wide:
'custom_rules' => [
    [
        'type'    => 'country',
        'value'   => 'XX',           // specific high-risk country
        'action'  => 'challenge',
    ],
    [
        'type'    => 'ua_contains',
        'value'   => 'GPTBot',        // specific bot
        'action'  => 'challenge',
    ],
],

'custom_rules' => [
    [
        'id'     => 'my_rule_1',                // optional, for logging
        'type'   => 'ip',                       // see types below
        'value'  => '203.0.113.0/24',           // see values below
        'action' => 'block',                    // allow | block | challenge | log
    ],
    [
        'id'     => 'my_rule_2',
        'type'   => 'ua_regex',
        'value'  => '/MyInternalScraper\/\d+\./i',
        'action' => 'log',
    ],
],

['type' => 'ip', 'value' => '198.51.100.0/24', 'action' => 'allow'],

[
    'type'   => 'ua_regex',
    'value'  => '/DataScraper\/[0-9]/i',
    'action' => 'block',
],

['type' => 'country', 'value' => 'XX', 'action' => 'challenge'],

[
    'type'    => 'header',
    'header'  => 'User-Agent',
    'value'   => 'HeadlessChrome',
    'action'  => 'challenge',
],

[
    'type'   => 'ip',
    'value'  => ['203.0.113.0/24', '198.51.100.0/24'],
    'action' => 'block',
],

'reverse_proxy' => [
    'enabled'   => true,
    'header'    => 'CF-Connecting-IP',   // or 'X-Forwarded-For' for AWS ALB
    'addresses' => [
        // Cloudflare IPv4 ranges (keep updated):
        '173.245.48.0/20',
        '103.21.244.0/22',
        '103.22.200.0/22',
        '103.31.4.0/22',
        // ... full list at https://www.cloudflare.com/ips/
    ],
],

// BAD: empty addresses = trust everyone = anyone can spoof their IP
'reverse_proxy' => ['enabled' => true, 'header' => 'X-Forwarded-For', 'addresses' => []],

// GOOD: trust only your CDN
'reverse_proxy' => ['enabled' => true, 'header' => 'CF-Connecting-IP', 'addresses' => $cf_ranges],

'performance' => [
    'skip_extensions' => [
        'css', 'js', 'png', 'jpg', 'jpeg', 'gif', 'ico', 'svg',
        'woff', 'woff2', 'ttf', 'eot', 'webp', 'avif', 'map', 'txt',
    ],
    'skip_paths' => [
        '/static/', '/assets/', '/media/', '/images/', '/css/',
        '/js/', '/fonts/', '/dist/', '/build/', '/vendor/', '/node_modules/',
    ],
],

$redis_cache = new RedisCache('redis://10.0.0.1:6379');
$config = new Configuration(
    // ... other settings
    cache: $redis_cache,
);
$bb = new BadBehaviour($config);

$ php bin/diagnose.php

{
    "safe_mode": false,
    "monitor_only_effective": true,
    "monitor_only": true,
    "strictness": "monitor-only",
    "preset": "minimal",
    "config_loaded": true,
    "logging_enabled": true,
    "detectors_active": {
        "blacklist": true,
        "bot": true,
        "dns_verify": false,
        "dyn_ranges": false,
        "rate_limit": false,
        "dnsbl": false,
        "behavioral": false,
        "fingerprint": false,
        "client_hints": false,
        "agentic": false,
        "head": false,
        "asset": false
    },
    "hint": "BadBehaviour is in monitor-only mode by configuration. ..."
}

$bb = new BadBehaviour($config);
$state = $bb->diagnostics();

// Use in health check endpoints:
return new JsonResponse($state);

-- 1. Did anything actually get a 403? (Should be tiny — empty UA + raw XSS only)
SELECT enforcement_action, COUNT(*)
FROM bad_behaviour
WHERE date >= CURDATE()
GROUP BY enforcement_action;

-- 2. What would have been blocked at 'normal' strictness?
SELECT status_code, COUNT(*)
FROM bad_behaviour
WHERE enforcement_action = 'monitored'
  AND date >= CURDATE()
GROUP BY status_code
ORDER BY COUNT(*) DESC;

-- 3. False positive candidates (legitimate-looking bots in monitored)
SELECT ip, user_agent, status_code, date
FROM bad_behaviour
WHERE enforcement_action = 'monitored'
  AND user_agent LIKE '%Googlebot%'   -- known search engines
LIMIT 100;

-- 4. Bot category breakdown
SELECT
    JSON_UNQUOTE(JSON_EXTRACT(metadata, '$.bot_category')) AS category,
    COUNT(*) AS n
FROM bad_behaviour
WHERE date >= CURDATE()
  AND JSON_EXTRACT(metadata, '$.bot_category') IS NOT NULL
GROUP BY category
ORDER BY n DESC;

<?php
return [
    'preset'     => 'minimal',
    'strictness' => 'monitor-only',
    'logging'    => true,
    'verbose'    => true,     // log allowed too
];

<?php
return [
    'preset'     => 'minimal',
    'strictness' => 'normal',
    'logging'    => true,

    // Aggressive AI crawler blocking
    'ai_crawlers' => [
        'allowed'          => [],                // allow NO AI crawlers
        'block_unverified' => true,              // any unverified AI = block
        'strict'           => true,              // any AI not on allowlist = block
    ],

    // robots.txt policy mirrors
    'bot_categories' => [
        'blocked' => ['ai_crawler', 'residential_proxy'],
        'allowed' => ['search_engine'],          // explicitly allow Google/Bing/etc
    ],

    // Be loud about scrapers
    'rate_limits' => [
        'enabled'    => true,
        'global'     => ['requests' => 500,  'window' => 3600],
        'per_minute' => ['requests' => 30,   'window' => 60],
    ],
];

<?php
return [
    'preset'     => 'minimal',
    'strictness' => 'normal',
    'logging'    => true,

    'bot_categories' => [
        'blocked'   => ['residential_proxy'],
        'challenge' => ['ai_crawler'],
        'allowed'   => [
            'search_engine',     // Google, Bing — critical for SEO
            'shopping_crawler',  // Google Shopping, Bing Shopping — critical for product visibility
            'cloud_infrastructure', // safety: CDN probes
        ],
    ],

    // Strict rate limits on checkout
    'rate_limits' => [
        'enabled' => true,
        'global'  => ['requests' => 2000, 'window' => 3600],
        'post'    => ['requests' => 100,  'window' => 3600],
        'login'   => ['requests' => 20,   'window' => 900],
    ],
];

<?php
return [
    'preset'     => 'minimal',
    'strictness' => 'normal',
    'logging'    => true,

    // Critical: trust Cloudflare's IP forwarding
    'reverse_proxy' => [
        'enabled'   => true,
        'header'    => 'CF-Connecting-IP',
        'addresses' => [
            // Current full list at https://www.cloudflare.com/ips/
            '173.245.48.0/20',
            '103.21.244.0/22',
            '103.22.200.0/22',
            '103.31.4.0/22',
            '141.101.64.0/18',
            '108.162.192.0/18',
            '190.93.240.0/20',
            '188.114.96.0/20',
            '197.234.240.0/22',
            '198.41.128.0/17',
            '162.158.0.0/15',
            '104.16.0.0/13',
            '104.24.0.0/14',
            '172.64.0.0/13',
            '131.0.72.0/22',
        ],
    ],

    // Use CF's JA3 forwarding
    'enable_fingerprinting' => true,
    'fingerprints' => [
        'bad_ja3' => [],   // populate after traffic analysis
    ],
];

<?php
return [
    'preset'     => 'minimal',
    'strictness' => 'normal',                  // start safe
    'logging'    => true,
    'verbose'    => true,                      // log everything for comparison

    // Carry over BB 2.x settings
    'reverse_proxy' => [
        'enabled'   => true,
        'header'    => 'X-Forwarded-For',
        'addresses' => ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'],
    ],
    'offsite_forms' => false,
    'httpbl' => [
        'key'    => 'your-key-here',
        'threat' => 25,
        'maxage' => 30,
    ],
];

$ php -r 'echo realpath("config/bb_config.php") ?: "NOT FOUND";'

$ php bin/diagnose.php

// 1. Is logging enabled?
echo $config->logging;   // should be true

// 2. Is the table writable?
// Check DB permissions for the bb user

// 3. Is install_once() running?
// Look for 'install_once' errors in your error log

SELECT ip, user_agent, status_code, date
FROM bad_behaviour
WHERE enforcement_action = 'enforced'
  AND (user_agent LIKE '%Googlebot%' OR user_agent LIKE '%Bingbot%')
ORDER BY date DESC
LIMIT 50;

-- What's realistic for legitimate users?
SELECT
    ip,
    COUNT(*) AS reqs,
    COUNT(*) / COUNT(DISTINCT DATE_FORMAT(date, '%Y-%m-%d %H:00:00')) AS per_hour
FROM bad_behaviour
WHERE enforcement_action = 'allowed'
  AND date >= NOW() - INTERVAL 7 DAY
GROUP BY ip
HAVING reqs > 100
ORDER BY per_hour DESC
LIMIT 50;

SELECT ip, user_agent, status_code
FROM bad_behaviour
WHERE user_agent LIKE 'Cloudflare%' OR user_agent LIKE 'ELB-HealthChecker%'
ORDER BY date DESC
LIMIT 20;

return [
    'strictness' => 'normal',
    'dnsbl_enabled' => false,                    // disable just DNSBL
    'enable_behavioral_analysis' => true,        // enable just behavioral
    'rate_limit_enabled' => false,               // disable just rate limits
];