Metadata-Version: 2.5
Name: stealth-browserctl
Version: 0.0.1
Summary: Browser automation toolkit with AI-powered assistant and proxy validation
Author-email: flyingyizi <flyingyizi@gmail.com>
Requires-Python: >=3.11
Requires-Dist: loguru>=0.7.2
Requires-Dist: mitmproxy>=11.0.2
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic>=2.13.3
Requires-Dist: python-daemon>=3.1.2
Requires-Dist: requests>=2.34.2
Requires-Dist: shortuuid>=1.0.13
Requires-Dist: typer>=0.24.2
Requires-Dist: websockets>=16.0
Description-Content-Type: text/markdown

# BrowserCtl

A browser automation toolkit for AI agents using undetected-chromedriver with daemon-based session management.

## Overview

BrowserCtl is a command-line interface for browser automation that integrates seamlessly with AI agents. It uses a **daemon server architecture** to maintain browser sessions across multiple command invocations, allowing you to execute multiple commands that operate on the same browser instance.

## Architecture

The tool consists of two main components:

1. **Daemon Server** (`browserctl daemon`): A background process that manages browser sessions
2. **CLI Client**: Commands that communicate with the daemon via Unix sockets



## Features

- **Browser Automation**: Open, close, and control browser sessions
- **Page Navigation**: Navigate to URLs, go back/forward, reload pages
- **Element Interaction**: Click, type, fill forms, drag and drop
- **Tab Management**: Create, close, and switch between tabs
- **Storage Management**: Handle cookies, localStorage, and sessionStorage
- **Network Control**: Route interception and network monitoring
- **DevTools Integration**: Console logs, performance tracing, element inspection
- **Multi-Session Support**: Run multiple isolated browser sessions
- **Stealth Mode**: Uses undetected-chromedriver to avoid detection

## Installation

```bash
# Install using uv
uv tool install browserctl

# Or run directly
uv run browserctl --help
```

## Quick Start

```bash
# Start the daemon (optional - will auto-start on first command)
browserctl daemon start

# Open a browser
browserctl open https://example.com

# Take a snapshot
browserctl snapshot

# Click an element (using ref from snapshot)
browserctl click e15

# Type text
browserctl type "search query"

# Press a key
browserctl press Enter

# Take a screenshot
browserctl screenshot

# Close the browser
browserctl close

# Stop the daemon
browserctl daemon stop
```

## Daemon Management

The daemon server manages all browser sessions:

```bash
# Start daemon
browserctl daemon start

# Check daemon status
browserctl daemon status

# Stop daemon
browserctl daemon stop

# Restart daemon
browserctl daemon restart

# Run daemon in foreground (for debugging)
browserctl daemon start --foreground
```

## Multi-Command Session Example

This demonstrates the key feature - multiple commands operating on the same browser:

```bash
# Command 1: Open browser in session "mysession"
browserctl open https://example.com --session mysession

# Command 2: Open new tab in the same session
browserctl tab-new https://example.com/other --session mysession

# Command 3: List tabs (shows both tabs)
browserctl tab-list --session mysession

# Command 4: Take screenshot
browserctl screenshot --session mysession

# Command 5: Close the session
browserctl close --session mysession
```

All these commands operate on the **same browser instance** because they use the same session name.

## Commands

### Core Commands

- `open [URL]` - Open a new browser session
- `close` - Close the browser session
- `goto <URL>` - Navigate to a URL
- `snapshot` - Take a page snapshot
- `screenshot` - Take a screenshot
- `pdf` - Save page as PDF
- `resize <width> <height>` - Resize viewport
- `eval <script>` - Execute JavaScript

### Interaction Commands

- `click <selector>` - Click an element
- `dblclick <selector>` - Double-click an element
- `type <text>` - Type text into focused element
- `fill <selector> <value>` - Fill an input field
- `press <key>` - Press a key
- `hover <selector>` - Hover over an element
- `drag <source> <target>` - Drag and drop
- `select <selector> <value>` - Select option
- `upload <file>` - Upload a file
- `check <selector>` - Check checkbox
- `uncheck <selector>` - Uncheck checkbox

### Navigation Commands

- `go-back` - Navigate back
- `go-forward` - Navigate forward
- `reload` - Reload page

### Tab Commands

- `tab-list` - List all tabs
- `tab-new [URL]` - Open new tab
- `tab-close [index]` - Close tab
- `tab-select <index>` - Select tab

### Storage Commands

- `state-save [filename]` - Save browser state
- `state-load <filename>` - Load browser state
- `cookie-list` - List cookies
- `cookie-get <name>` - Get cookie value
- `cookie-set <name> <value>` - Set cookie
- `cookie-delete <name>` - Delete cookie
- `cookie-clear` - Clear all cookies
- `localstorage-list` - List localStorage
- `localstorage-get <key>` - Get localStorage item
- `localstorage-set <key> <value>` - Set localStorage item
- `localstorage-delete <key>` - Delete localStorage item
- `localstorage-clear` - Clear localStorage
- `sessionstorage-*` - Similar commands for sessionStorage

### Network Commands

- `route <pattern>` - Set network route
- `route-list` - List routes
- `unroute [pattern]` - Remove route

### DevTools Commands

- `console` - Show console logs
- `network` - Show network logs
- `run-code <code>` - Run custom code
- `tracing-start` - Start performance tracing
- `tracing-stop` - Stop performance tracing
- `pick` - Pick element interactively
- `highlight <selector>` - Highlight element

### Session Management

- `list` - List all browser sessions
- `close-all` - Close all sessions
- `kill-all` - Kill all browser processes
- `delete-data` - Delete session data

## Multi-Session Support

Run multiple isolated browser sessions:

```bash
# Session 1
browserctl -s=session1 open https://site1.com

# Session 2
browserctl -s=session2 open https://site2.com

# Work with session 1
browserctl -s=session1 snapshot

# Work with session 2
browserctl -s=session2 snapshot

# Close all
browserctl close-all
```

## Options

### Global Options

- `-s, --session <name>` - Browser session name
- `--raw` - Output raw data without formatting
- `--json` - Output as JSON

### Browser Options

- `--browser <type>` - Browser type (chrome, firefox, webkit, msedge)
- `--persistent` - Use persistent profile
- `--profile <path>` - Custom profile directory
- `--headed` - Run in headed mode (visible browser)
- `--config <file>` - Configuration file

## Element Selectors

Elements can be selected using:

1. **Refs** - From snapshot (e.g., `e15`)
2. **CSS Selectors** - Standard CSS (e.g., `#main > button.submit`)
3. **selenium Locators** - 
4. **Test IDs** - (e.g., `getByTestId('submit-button')`)

## Examples

### Form Submission

```bash
browserctl open https://example.com/form
browserctl snapshot
browserctl fill e1 "user@example.com"
browserctl fill e2 "password123"
browserctl click e3
browserctl snapshot
browserctl close
```

### Multi-Tab Workflow

```bash
browserctl open https://example.com
browserctl tab-new https://example.com/other
browserctl tab-list
browserctl tab-select 0
browserctl snapshot
browserctl close
```

### Authentication Flow

```bash
# Save authentication state
browserctl open https://app.example.com/login
browserctl fill "#email" "user@example.com"
browserctl fill "#password" "password"
browserctl click "#submit"
browserctl state-save auth.json
browserctl close

# Later, load authentication state
browserctl open https://app.example.com
browserctl state-load auth.json
```

## Architecture

The project is structured as follows:

```
browserctl/
├── src/
│   ├── stealth_cli/          # Main package entry point
│   │   └── __init__.py
│   └── cli_client/           # CLI implementation
│       ├── __init__.py       # Typer app and command definitions
│       ├── browser.py        # Browser manager and session handling
│       └── commands/         # Command implementations
│           ├── core_commands.py
│           ├── interaction_commands.py
│           ├── navigation_commands.py
│           ├── tab_commands.py
│           ├── storage_commands.py
│           ├── network_commands.py
│           ├── devtools_commands.py
│           └── session_commands.py
├── pyproject.toml
└── README.md
```

## Dependencies

- **typer** - CLI framework
- **undetected-chromedriver** - Stealth browser automation
- **selenium** - Browser automation framework
- **pydantic** - Data validation
- **loguru** - Logging

## Development

```bash
# Install dependencies
uv sync

# Run CLI
uv run browserctl --help

# Run tests
python test_basic.py
```

## License

MIT License

## Contributing

Contributions are welcome! Please submit pull requests or open issues on the repository.

# 检测网站

https://bot.sannysoft.com/

## 1. [BrowserLeaks](https://browserleaks.com/)

BrowserLeaks 显示泄露的个人数据，并提供相关文章帮助你理解每个部分和如何更好地保护自己。

### 检测项目

- IP 地址
- JavaScript
- WebRTC 泄露测试
- Canvas 指纹
- WebGL 报告
- 字体指纹
- 地理位置 API
- 功能检测
- 内容过滤器
- Java Applet
- Flash Player
- Silverlight

注意在使用前阅读其隐私政策以确保数据不被第三方服务收集。

## 2. [AmIUnique](https://amiunique.org/)

AmIUnique 不仅提供关于配置的信息，还研究浏览器指纹的多样性。点击主页上的“查看我的浏览器指纹”按钮即可测试。


### 检测信息

- 操作系统
- 浏览器及版本
- 时区和语言
- HTTP headers 属性
- JavaScript 属性

## 3. [Cover Your Tracks](https://coveryourtracks.eff.org/)

Cover Your Tracks 帮助你了解自己在追踪器面前的表现，并提供保护建议。


### 功能

- 提供详细的检测结果
- 提供保护建议

## 4. [Device Info](https://www.deviceinfo.me/)

Device Info 测试多个浏览器指纹指标，提供详细信息。


## 5. [CreepJS](https://abrahamjuliot.github.io/creepjs/)

CreepJS 提供详细的指纹分析，显示用户相同元素的比例。


## 6. [BrowserSPY](http://browserspy.dk/vbscript.php)

BrowserSPY 自 1999 年起提供服务，允许用户选择特定元素进行测试。


## 7. [Leaks Radar](https://leaksradar.com/index#allInformation)

Leaks Radar 提供基本信息，并在“指纹”部分提供浏览器指纹知识。


## 8. [Pixelscan](https://pixelscan.net/)

Pixelscan 检测浏览器指纹参数之间的不规则连接。


## 9. [Iphey](https://iphey.com/)

Iphey 检查你的数字身份是否可信，提供详细信息。
