From 2e3895f1bf55db96785ba5361d1b95c5373e12dc Mon Sep 17 00:00:00 2001 From: Luciabrightcode Date: Tue, 23 Dec 2025 11:46:18 +0800 Subject: [PATCH] Updated implementation plan and walkthough --- implementation_plan.md | 59 +++++++++++++++++++++--------------------- walkthrough.md | 11 ++++++++ 2 files changed, 41 insertions(+), 29 deletions(-) diff --git a/implementation_plan.md b/implementation_plan.md index 85a1d72..027bcc9 100644 --- a/implementation_plan.md +++ b/implementation_plan.md @@ -1,45 +1,46 @@ -# Phase 2: Core Components (Headless-Plus) Implementation Plan +# Phase 3: Evasion & Resilience Implementation Plan ## Goal Description -Implement the core logic for the "Headless-Plus" architecture: -1. **Browser Tier**: `CamoufoxManager` to handle browser instantiation, profile injection, and state extraction. -2. **Extractor Tier**: `CurlCffiClient` to consume shared state and execute high-speed requests with matching fingerprints. +Implement the "Human" behavior layer to defeat behavioral biometrics and temporal analysis. This phase focuses on: +1. **GhostCursorEngine**: Simulating human mouse movements (Bezier curves, Fitts's Law). +2. **EntropyScheduler**: Maximizing temporal entropy in request scheduling (Gaussian noise, Phase drift). +3. **ProxyRotator**: Managing IP reputation with sticky sessions and rapid rotation for new sessions. ## User Review Required > [!IMPORTANT] -> **Mocking Strategy**: Since we might not have a live "Cloudflare-protected" target easily accessible for automated testing, I will implement a **Mock Target** using a local `http.server` or `FastAPI` that logs headers/TLS info to verify fingerprints. +> **GhostCursor tuning**: The velocity parameters (`a=0.1`, `b=0.15`) are empirical starting points from the ADD. We may need to tune these against a live detection system if possible, or rely on the visual verification tool. ## Proposed Changes -### Browser Tier -#### [NEW] [src/browser/manager.py](file:///home/kasm-user/workspace/FAEA/src/browser/manager.py) -- **Class**: `CamoufoxManager` -- **Responsibilities**: - - Launch Camoufox (via Playwright) with specific `user_agent` and `viewport`. - - `initialize()`: Set up browser context. - - `extract_session_state()`: Gather cookies, storage, and fingerprint info into `SessionState`. - - **Safety**: Implement `__aenter__` and `__aexit__` for aggressively reclaiming memory (close context/page). +### Browser Tier (Human Mimesis) +#### [NEW] [src/browser/ghost_cursor.py](file:///home/kasm-user/workspace/FAEA/src/browser/ghost_cursor.py) +- **Class**: `GhostCursorEngine` +- **Features**: + - `move_to(page, x, y)`: Generates composite cubic Bezier curves. + - `_generate_waypoints()`: Adds Gaussian perturbation to path. + - `_execute_submovement()`: Applies velocity profile based on Fitts's Law. + - `random_micro_movement()`: Simulates reading/idling jitter. -### Extractor Tier -#### [NEW] [src/extractor/client.py](file:///home/kasm-user/workspace/FAEA/src/extractor/client.py) -- **Class**: `CurlClient` -- **Responsibilities**: - - Initialize with `SessionState`. - - Configure `curl_cffi` session to match `SessionState.tls_fingerprint`. - - `fetch(url)`: Execute requests using the shared state. +### Core Tier (Temporal & Network Entropy) +#### [NEW] [src/core/scheduler.py](file:///home/kasm-user/workspace/FAEA/src/core/scheduler.py) +- **Class**: `EntropyScheduler` +- **Features**: + - `next_execution_time()`: Calculates delays using `Base + Gaussian(0, 5s) + PhaseDrift`. + - Phase shift accumulating over time to avoid periodic harmonics. -### Testing Infrastructure -#### [NEW] [tests/e2e/test_handover.py](file:///home/kasm-user/workspace/FAEA/tests/e2e/test_handover.py) -- **TLS Verification**: The automated test will likely use a local mock for Header/Cookie verification. -- **Manual JA3 Verification**: A separate script `tests/manual/verify_tls.py` will be created to hit an external service (e.g., `https://tls.peet.ws/api/all`) to print and compare JA3 hashes from both Camoufox and CurlClient. This addresses the "High Risk" feedback by acknowledging external dependency for true TLS verification. +#### [NEW] [src/core/proxy.py](file:///home/kasm-user/workspace/FAEA/src/core/proxy.py) +- **Class**: `MobileProxyRotator` +- **Features**: + - `select_proxy(session_id)`: Enforces sticky sessions (same session -> same IP). + - Cooldown tracking: Prevents reusing IPs too quickly after session termination. ## Verification Plan ### Automated Tests -1. **Mock Server Test**: - - Start a local server that captures headers. - - Run the E2E script. - - Assert that both Browser and Client requests look identical (or sufficiently similar). +- **Unit Tests**: Verify math logic for Bezier curves and Scheduler distribution. + - `tests/unit/test_ghost_cursor.py` (check point generation bounds) + - `tests/unit/test_scheduler.py` (verify distribution mean/stddev) ### Manual Verification -- Run `docker-compose up` and execute a manual script inside the orchestrator container to trigger the flow. +- **Visual Check**: Use `tests/manual/verify_cursor.py` (to be created) to visualize the cursor path on a canvas or plot, ensuring it looks "human-like" and not robotic straight lines. +- **Log Analysis**: Review scheduler logs to ensure no obvious repeatable patterns in timing. diff --git a/walkthrough.md b/walkthrough.md index f0a882b..8bfd5ab 100644 --- a/walkthrough.md +++ b/walkthrough.md @@ -71,3 +71,14 @@ tests/unit/test_session_core.py .. [100%] - Address TLS Mismatch (Phase 3). - Implement persistent Redis loops. +## Phase 3: Evasion & Resilience Walkthrough + +### 1. Goals +- **GhostCursorEngine**: Implement human-like mouse trajectories using Bezier curves and Fitts's Law. +- **EntropyScheduler**: Implement jittered request scheduling with Gaussian noise and phase drift. +- **ProxyRotator**: Implement sticky session management for mobile proxies. + +### 2. Next Steps +- Implement `src/browser/ghost_cursor.py`. +- Implement `src/core/scheduler.py`. +- Implement `src/core/proxy.py`.