Garfield

Garfield is an advanced browser automation and traffic simulation bot designed to mimic human behavior using Selenium and Python. It manages multiple concurrent browser sessions with proxy validation and randomized interaction patterns.

Features

• Concurrent Execution: Uses asyncio and thread pools to run multiple browser sessions simultaneously without blocking.
• Efficient Proxy Management: Validates proxies using lightweight requests calls before launching heavy browser instances.
• Human-like Interaction: Implements random scrolling, waiting, and clicking behaviors to simulate real user activity.
• Dockerized: Fully containerized environment for easy deployment.
• Configurable: Extensive configuration options for scheduling, probabilities, and targets.

Prerequisites

• Python: 3.13+
• Poetry: For dependency management
• Firefox: Required for Selenium WebDriver (installed automatically in Docker image)
• Oxylabs account: For proxy rotation

Installation

1. Clone the repository:

   git clone <repository-url>
   cd garfield

2. Install dependencies:

   poetry install

3. Install Browser Drivers:

   python driver_chk.py

Configuration

Environment Variables

Create a .env file in the /config directory (or root, depending on your setup) with the following key variables:

Variable	Description
user	Proxy username
pass1	Proxy password
endpoint	Proxy host/port
prox_test	URL to test proxy connectivity (e.g., https://iplocation.io)
host	The IP/Host to AVOID (ensure proxy is working)
stay_on_target	Main target URL to visit
teezy	Timezone string (e.g., America/New_York)
burt	XPath for a specific element to click if found
sub1 - sub4	Sub-paths to visit on the target site

Tuning

Edit config.py to adjust bot behavior:

• scheduler: Hourly probability weights.
• upl_time: Random sleep intervals.
• subs: Probability distribution for visiting sub-pages.
• downity / uppity: Rate limit ranges.

Usage

Running Locally

To start the bot manually:

poetry run python modules.py

Running with Docker

1. Build the image:

   docker build -t garfield .

2. Run the container:

   docker run -d --env-file .env -v $(pwd)/logs:/app/logs garfield

Structure

• modules.py: Main entry point and logic engine.
• Dockerfile: Container configuration.
• config.py: Behavior configuration parameters.
• ua.py: List of user agents for rotation.
• pre.py: Pre-visit URL list (warm-up).
• driver_chk.py: Utility to ensure GeckoDriver is installed.