WAGERBABE DOCS
All Stories
4-5-3-bot-detectionDoneEpic 4.5

Story 4.5.3: Bot Detection

Status: done

Tasks

  • **Task 1: Datacenter IP Detection** (AC: 1)
    • 1.1 Create BotDetector class in `server/app/services/fraud/bot_detector.py`
    • 1.2 Implement CIDR range matching for cloud providers
    • 1.3 Pre-compiled IP networks for O(1) lookup performance
    • 1.4 Add `is_datacenter_ip(ip)` method and async `_check_datacenter_ip()`
  • **Task 2: IP Reputation Integration** (AC: 2)
    • 2.1 Create IP reputation client interface
    • 2.2 Implement IPQualityScore adapter with async HTTP
    • 2.3 Add Redis caching layer (1hr TTL)
    • 2.4 Create IPReputation dataclass with is_vpn, is_proxy, fraud_score
  • **Task 3: CAPTCHA Challenge System** (AC: 3)
    • 3.1 Track suspicious actions in Redis: `suspicious:{session_id}`
    • 3.2 Implement CAPTCHA trigger logic (3+ actions)
    • 3.3 Integrate hCaptcha verification endpoint
    • 3.4 Add CAPTCHA response handling in bot protection middleware
  • **Task 4: Device Fingerprinting** (AC: 4)
    • 4.1 Create device_fingerprints table migration
    • 4.2 Database schema ready for client fingerprint collection
    • 4.3 Store fingerprint hash with user association
    • 4.4 Implement `_check_fingerprint()` and `flag_fingerprint()` methods
    • 4.5 Track first_seen_at, last_seen_at, use_count
  • **Task 5: IP Rate Limiting** (AC: 5)
    • 5.1 Create rate limiter in BotDetector
    • 5.2 Implement Redis-based counter with 60s expiry
    • 5.3 Return 429 with Retry-After header
    • 5.4 Add IP whitelist for agents
    • 5.5 Log rate limit violations
  • **Task 6: Event Logging** (AC: 6)
    • 6.1 Create bot_detection_events table migration
    • 6.2 Implement `_log_check_event()` method
    • 6.3 Add indexes for analytics queries (GIN on checks_failed)
    • 6.4 Create daily stats aggregation view
  • **Task 7: BotDetector Orchestration**
    • 7.1 Implement `check_request(request)` main method
    • 7.2 Combine all checks with weighted scoring
    • 7.3 Determine action: ALLOW, CAPTCHA, BLOCK, RATE_LIMIT
    • 7.4 Create BotProtectionMiddleware for FastAPI
  • **Task 8: Testing**
    • 8.1 Unit tests for each detection method (103 tests)
    • 8.2 Tests with mock IP reputation
    • 8.3 Rate limit tests
    • 8.4 CAPTCHA flow E2E tests (deferred)

Progress

Tasks8/8
Acceptance Criteria0
Total Tasks8

Navigation

View Epic 4.5All Stories