luciabrightcode/FAEA
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updated implementation plan and walkthough

Browse source
This commit is contained in:
Luciabrightcode 2025-12-23 11:46:18 +08:00
parent 1134da7ed3
commit 2e3895f1bf
2 changed files with 41 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
implementation_plan.md
View file

@ -1,45 +1,46 @@
# Phase 2: Core Components (Headless-Plus) Implementation Plan # Phase 3: Evasion & Resilience Implementation Plan
## Goal Description ## Goal Description
Implement the core logic for the "Headless-Plus" architecture: Implement the "Human" behavior layer to defeat behavioral biometrics and temporal analysis. This phase focuses on:
1. **Browser Tier**: `CamoufoxManager` to handle browser instantiation, profile injection, and state extraction. 1. **GhostCursorEngine**: Simulating human mouse movements (Bezier curves, Fitts's Law).
2. **Extractor Tier**: `CurlCffiClient` to consume shared state and execute high-speed requests with matching fingerprints. 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 ## User Review Required
> [!IMPORTANT] > [!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 ## Proposed Changes
### Browser Tier ### Browser Tier (Human Mimesis)
#### [NEW] [src/browser/manager.py](file:///home/kasm-user/workspace/FAEA/src/browser/manager.py) #### [NEW] [src/browser/ghost_cursor.py](file:///home/kasm-user/workspace/FAEA/src/browser/ghost_cursor.py)
- **Class**: `CamoufoxManager` - **Class**: `GhostCursorEngine`
- **Responsibilities**: - **Features**:
- Launch Camoufox (via Playwright) with specific `user_agent` and `viewport`. - `move_to(page, x, y)`: Generates composite cubic Bezier curves.
- `initialize()`: Set up browser context. - `_generate_waypoints()`: Adds Gaussian perturbation to path.
- `extract_session_state()`: Gather cookies, storage, and fingerprint info into `SessionState`. - `_execute_submovement()`: Applies velocity profile based on Fitts's Law.
- **Safety**: Implement `__aenter__` and `__aexit__` for aggressively reclaiming memory (close context/page). - `random_micro_movement()`: Simulates reading/idling jitter.
### Extractor Tier ### Core Tier (Temporal & Network Entropy)
#### [NEW] [src/extractor/client.py](file:///home/kasm-user/workspace/FAEA/src/extractor/client.py) #### [NEW] [src/core/scheduler.py](file:///home/kasm-user/workspace/FAEA/src/core/scheduler.py)
- **Class**: `CurlClient` - **Class**: `EntropyScheduler`
- **Responsibilities**: - **Features**:
- Initialize with `SessionState`. - `next_execution_time()`: Calculates delays using `Base + Gaussian(0, 5s) + PhaseDrift`.
- Configure `curl_cffi` session to match `SessionState.tls_fingerprint`. - Phase shift accumulating over time to avoid periodic harmonics.
- `fetch(url)`: Execute requests using the shared state.
### Testing Infrastructure #### [NEW] [src/core/proxy.py](file:///home/kasm-user/workspace/FAEA/src/core/proxy.py)
#### [NEW] [tests/e2e/test_handover.py](file:///home/kasm-user/workspace/FAEA/tests/e2e/test_handover.py) - **Class**: `MobileProxyRotator`
- **TLS Verification**: The automated test will likely use a local mock for Header/Cookie verification. - **Features**:
- **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. - `select_proxy(session_id)`: Enforces sticky sessions (same session -> same IP).
- Cooldown tracking: Prevents reusing IPs too quickly after session termination.
## Verification Plan ## Verification Plan
### Automated Tests ### Automated Tests
1. **Mock Server Test**: - **Unit Tests**: Verify math logic for Bezier curves and Scheduler distribution.
- Start a local server that captures headers. - `tests/unit/test_ghost_cursor.py` (check point generation bounds)
- Run the E2E script. - `tests/unit/test_scheduler.py` (verify distribution mean/stddev)
- Assert that both Browser and Client requests look identical (or sufficiently similar).
### Manual Verification ### 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.

11
walkthrough.md
View file

@ -71,3 +71,14 @@ tests/unit/test_session_core.py .. [100%]
- Address TLS Mismatch (Phase 3). - Address TLS Mismatch (Phase 3).
- Implement persistent Redis loops. - 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`.