Help us shape the future of Go! Take the 2026 Go Developer Survey

osciris

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2025 License: MIT Imports: 14 Imported by: 0

README

Osciris

Библиотека-обертка над chromedp для Go с интеграцией fingerprint injection. Упрощает работу с автоматизацией браузера и защитой от детекции.

🚀 Возможности

  • ✅ Простой и удобный API для работы с chromedp
  • ✅ Интеграция с fingerprint-injector-go
  • ✅ Поддержка stealth режима
  • ✅ Готовые пресеты fingerprint
  • ✅ Упрощенная работа со страницами и элементами
  • ✅ Автоматическое применение fingerprint при создании браузера
  • ✅ Работа с удаленным браузером через NewRemoteAllocator
  • ✅ Управление вкладками: открытие, подключение к существующим, закрытие
  • ✅ Избежание создания дублирующих вкладок при переподключении

📦 Установка

go get github.com/playy/osciris

🎯 Быстрый старт

Базовое использование
package main

import (
    "context"
    "log"
    
    "github.com/playy/osciris"
    fp "github.com/vitaliitsarov/fingerprint-injector-go"
)

func main() {
    ctx := context.Background()
    
    // Создаем браузер с fingerprint
    browser, err := osciris.NewBrowser(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer browser.Close()
    
    // Создаем страницу
    page := browser.NewPage()
    
    // Переходим на сайт
    err = page.Navigate("https://example.com")
    if err != nil {
        log.Fatal(err)
    }
    
    // Получаем заголовок
    var title string
    err = page.Title(&title)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Title: %s", title)
}
Кастомные опции
options := &osciris.BrowserOptions{
    Headless:    false,
    Stealth:     true,
    Timeout:     30 * time.Second,
    WindowWidth: 1920,
    WindowHeight: 1080,
    Fingerprint: fp.NewChrome119Windows11(),
    UserDataDir: "./chrome-data",
}

browser, err := osciris.NewBrowser(ctx, options)
Кастомный fingerprint
fingerprint := &fp.Fingerprint{
    UserAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    Platform:  "Win32",
    WebGL: &fp.WebGL{
        Vendor:   "Google Inc. (NVIDIA)",
        Renderer: "ANGLE (NVIDIA GeForce RTX 3080)",
    },
    Canvas: &fp.Canvas{
        Noise: 0.02,
    },
    WebRTC: &fp.WebRTC{
        Disable: true,
    },
}

options := osciris.DefaultBrowserOptions()
options.Fingerprint = fingerprint

browser, err := osciris.NewBrowser(ctx, options)
Работа с удаленным браузером

Важно: Перед подключением к удаленному браузеру, Chrome должен быть запущен с флагом удаленной отладки:

# Windows
chrome.exe --remote-debugging-port=17986

# Linux/Mac
google-chrome --remote-debugging-port=17986
# или
chromium --remote-debugging-port=17986

// Подключаемся к удаленному браузеру
remoteURL := "http://127.0.0.1:17986"

browser, err := osciris.NewRemoteBrowser(ctx, remoteURL, nil)
if err != nil {
    log.Fatal(err)
}
defer browser.Close()

// Получаем список всех вкладок
tabs, err := browser.ListTabs()
if err != nil {
    log.Fatal(err)
}

// Подключаемся к существующей вкладке (избегает создания новой)
if len(tabs) > 0 {
    tabBrowser, err := browser.ConnectToTab(tabs[0].ID)
    if err != nil {
        log.Fatal(err)
    }
    defer tabBrowser.Close()
    
    page := tabBrowser.NewPage()
    page.Navigate("https://example.com")
}

// Открываем новую вкладку
newTab, err := browser.OpenTab("https://example.com")
if err != nil {
    log.Fatal(err)
}
defer newTab.Close()

// Получаем ID текущей вкладки
tabID := newTab.GetTargetID()
log.Printf("Tab ID: %s", tabID)

📖 API Reference

Browser
NewBrowser

Создает новый экземпляр браузера.

browser, err := osciris.NewBrowser(ctx, options)
BrowserOptions
type BrowserOptions struct {
    Headless     bool              // Headless режим
    UserDataDir  string            // Директория для данных браузера
    Fingerprint  *fp.Fingerprint   // Fingerprint для инжектирования
    Stealth      bool              // Stealth режим
    Timeout      time.Duration     // Timeout для операций
    Flags        []string          // Дополнительные флаги Chrome
    WindowWidth  int               // Ширина окна
    WindowHeight int               // Высота окна
    RemoteURL    string            // Адрес удаленного браузера (например, "http://127.0.0.1:17986")
    TargetID     target.ID         // ID существующей вкладки для подключения
}
Методы Browser
  • Context() context.Context - Возвращает context браузера
  • Close() error - Закрывает браузер
  • Run(...chromedp.Action) error - Выполняет действия chromedp
  • NewPage() *Page - Создает новую страницу
  • ListTabs() ([]Tab, error) - Возвращает список всех вкладок (только для удаленного браузера)
  • OpenTab(url string) (*Browser, error) - Открывает новую вкладку (только для удаленного браузера)
  • ConnectToTab(targetID target.ID) (*Browser, error) - Подключается к существующей вкладке (только для удаленного браузера)
  • CloseTab() error - Закрывает текущую вкладку (только для удаленного браузера)
  • GetTargetID() target.ID - Возвращает ID текущей вкладки
Tab

Структура, представляющая вкладку браузера.

type Tab struct {
    ID       target.ID  // Уникальный идентификатор вкладки
    Type     string     // Тип вкладки (обычно "page")
    Title    string     // Заголовок вкладки
    URL      string     // URL вкладки
    Attached bool       // Подключена ли вкладка
}
NewRemoteBrowser

Создает подключение к удаленному браузеру.

browser, err := osciris.NewRemoteBrowser(ctx, "http://127.0.0.1:17986", options)
Page
Методы Page
  • Navigate(url string) error - Переходит по URL
  • NavigateAndWait(url, waitVisible string) error - Переходит и ждет элемент
  • WaitVisible(selector string) error - Ждет появления элемента
  • Click(selector string) error - Кликает по элементу
  • SendKeys(selector, text string) error - Отправляет текст
  • Value(selector string, result *string) error - Получает значение
  • Text(selector string, result *string) error - Получает текст
  • Screenshot(buf *[]byte) error - Делает скриншот
  • Evaluate(expression string, result interface{}) error - Выполняет JavaScript
  • Reload() error - Перезагружает страницу
  • Back() error - Возвращается назад
  • Forward() error - Переходит вперед
  • Title(result *string) error - Получает заголовок
  • URL(result *string) error - Получает URL
  • RunActions(...chromedp.Action) error - Выполняет произвольные действия

💡 Примеры

Удаленный браузер и управление вкладками
// Подключаемся к удаленному браузеру
browser, _ := osciris.NewRemoteBrowser(ctx, "http://127.0.0.1:17986", nil)

// Получаем список вкладок
tabs, _ := browser.ListTabs()
for _, tab := range tabs {
    log.Printf("Tab: %s - %s", tab.Title, tab.URL)
}

// Подключаемся к существующей вкладке
if len(tabs) > 0 {
    tabBrowser, _ := browser.ConnectToTab(tabs[0].ID)
    page := tabBrowser.NewPage()
    page.Navigate("https://example.com")
}

// Открываем новую вкладку
newTab, _ := browser.OpenTab("https://google.com")
defer newTab.Close()
Работа с формами
page := browser.NewPage()
page.Navigate("https://example.com/login")
page.SendKeys("#username", "user123")
page.SendKeys("#password", "pass123")
page.Click("#submit")
page.WaitVisible(".success-message")
Скриншот
var buf []byte
err := page.Screenshot(&buf)
if err != nil {
    log.Fatal(err)
}

err = os.WriteFile("screenshot.png", buf, 0644)
JavaScript выполнение
var result string
err := page.Evaluate(`document.querySelector("h1").textContent`, &result)
Использование chromedp напрямую
err := page.RunActions(
    chromedp.WaitVisible("#element"),
    chromedp.Click("#button"),
    chromedp.Sleep(2*time.Second),
)

🛡️ Stealth режим

По умолчанию включен stealth режим, который:

  • Отключает признаки автоматизации
  • Скрывает webdriver флаги
  • Применяет fingerprint injection

Для отключения:

options := osciris.DefaultBrowserOptions()
options.Stealth = false

📁 Примеры

В папке examples/ вы найдете полные примеры использования:

  • examples/basic/ - Базовое использование с preset
  • examples/custom/ - Использование кастомного fingerprint
  • examples/stealth/ - Максимальная защита от детекции
  • examples/remote/ - Работа с удаленным браузером и управление вкладками

Запуск примеров:

cd examples/basic
go run main.go

# Для удаленного браузера сначала запустите Chrome:
# chrome --remote-debugging-port=17986
# Затем запустите пример:
cd examples/remote
go run main.go

🔗 Интеграция с fingerprint-injector-go

Osciris полностью интегрирован с fingerprint-injector-go. Все пресеты и настройки fingerprint доступны:

// Использование готовых пресетов
options.Fingerprint = fp.NewChrome119Windows11()
options.Fingerprint = fp.NewChrome119MacOS()
options.Fingerprint = fp.NewChrome119Linux()

// Кастомная настройка
fingerprint := fp.NewChrome119Windows11()
fingerprint.WebRTC.Disable = true
fingerprint.Canvas.Noise = 0.05
options.Fingerprint = fingerprint

📝 Лицензия

MIT

🤝 Вклад

Пул реквесты приветствуются!

⚠️ Дисклеймер

Этот инструмент предназначен только для легитимных целей:

  • Тестирование защиты от ботов
  • Автоматизация тестирования
  • Исследование browser fingerprinting

Не используйте для обхода систем защиты или других незаконных действий.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Browser 

type Browser struct {
	// contains filtered or unexported fields
}

Browser представляет браузер с поддержкой fingerprint injection

func NewBrowser 

func NewBrowser(ctx context.Context, options *BrowserOptions) (*Browser, error)

NewBrowser создает новый экземпляр браузера

func NewRemoteBrowser 

func NewRemoteBrowser(ctx context.Context, remoteURL string, options *BrowserOptions) (*Browser, error)

NewRemoteBrowser создает подключение к удаленному браузеру Если не указан TargetID, создается новая вкладка

func NewRemoteBrowserManager 

func NewRemoteBrowserManager(ctx context.Context, remoteURL string, options *BrowserOptions) (*Browser, error)

NewRemoteBrowserManager создает подключение к удаленному браузеру БЕЗ создания новой вкладки Используется для управления браузером (получение списка вкладок, создание новых и т.д.)

func (*Browser) Close 

func (b *Browser) Close() error

Close закрывает браузер и освобождает ресурсы

func (*Browser) CloseTab 

func (b *Browser) CloseTab() error

CloseTab закрывает текущую вкладку (только для удаленного браузера)

func (*Browser) CloseTabByID 

func (b *Browser) CloseTabByID(targetID target.ID) error

CloseTabByID закрывает вкладку по её ID Использует временный контекст для закрытия вкладки через CDP

func (*Browser) ConnectToTab 

func (b *Browser) ConnectToTab(targetID target.ID) (*Browser, error)

ConnectToTab подключается к существующей вкладке по ID

func (*Browser) Context 

func (b *Browser) Context() context.Context

Context возвращает context браузера

func (*Browser) GetTargetID 

func (b *Browser) GetTargetID() target.ID

GetTargetID возвращает ID текущей вкладки

func (*Browser) ListTabs 

func (b *Browser) ListTabs() ([]Tab, error)

ListTabs возвращает список всех вкладок браузера

func (*Browser) NewPage 

func (b *Browser) NewPage() *Page

NewPage создает новую страницу

func (*Browser) OpenTab 

func (b *Browser) OpenTab(url string) (*Browser, error)

OpenTab открывает новую вкладку в браузере

func (*Browser) Run 

func (b *Browser) Run(actions ...chromedp.Action) error

Run выполняет действия в браузере

type BrowserOptions 

type BrowserOptions struct {
	// Headless режим
	Headless bool

	// UserDataDir для сохранения данных браузера
	UserDataDir string

	// Fingerprint для инжектирования
	Fingerprint *fp.Fingerprint

	// Stealth режим (дополнительные флаги для скрытия автоматизации)
	Stealth bool

	// Timeout для операций
	Timeout time.Duration

	// Дополнительные флаги Chrome
	Flags []string

	// Window размеры
	WindowWidth  int
	WindowHeight int

	// RemoteURL адрес удаленного браузера (например, "http://127.0.0.1:17986")
	// Если указан, будет использован NewRemoteAllocator вместо NewExecAllocator
	RemoteURL string

	// TargetID ID существующей вкладки для подключения
	// Если указан, будет подключение к существующей вкладке вместо создания новой
	TargetID target.ID
}

BrowserOptions содержит опции для создания браузера

func DefaultBrowserOptions 

func DefaultBrowserOptions() *BrowserOptions

DefaultBrowserOptions возвращает опции по умолчанию

type Page 

type Page struct {
	// contains filtered or unexported fields
}

Page представляет страницу браузера

func (*Page) AddScriptToEvaluateOnNewDocument 

func (p *Page) AddScriptToEvaluateOnNewDocument(jsCode string) error

AddScriptToEvaluateOnNewDocument добавляет скрипт, который выполняется на каждой новой странице

func (*Page) Back 

func (p *Page) Back() error

Back возвращается назад

func (*Page) ClearInput 

func (p *Page) ClearInput(selector string) error

ClearInput очищает поле ввода

func (*Page) Click 

func (p *Page) Click(selector string) error

Click кликает по элементу

func (*Page) ClickElementWithCtrl 

func (p *Page) ClickElementWithCtrl(selector string) error

ClickElementWithCtrl выполняет Ctrl+Click по элементу (открытие в новой вкладке)

func (*Page) ClickOnNewTab 

func (p *Page) ClickOnNewTab(selector string) error

ClickOnNewTab выполняет Ctrl+Click по элементу для открытия в новой вкладке Прокручивает к элементу и кликает с модификатором Ctrl

func (*Page) ClickWithScroll 

func (p *Page) ClickWithScroll(selector string) error

ClickWithScroll прокручивает к элементу и кликает по нему

func (*Page) ClickXY 

func (p *Page) ClickXY(x, y float64) error

ClickXY кликает по координатам

func (*Page) Evaluate 

func (p *Page) Evaluate(expression string, result interface{}) error

Evaluate выполняет JavaScript и возвращает результат

func (*Page) FastCheckElement 

func (p *Page) FastCheckElement(selector string) bool

FastCheckElement быстро проверяет наличие элемента без ожидания (с коротким таймаутом)

func (*Page) FastWaitForElement 

func (p *Page) FastWaitForElement(selector string, maxWaitMs int) error

FastWaitForElement быстро ждет появления элемента с коротким таймаутом

func (*Page) Focus 

func (p *Page) Focus(selector string) error

Focus устанавливает фокус на элемент

func (*Page) Forward 

func (p *Page) Forward() error

Forward переходит вперед

func (*Page) GetElementAttributes 

func (p *Page) GetElementAttributes(nodeID cdp.NodeID) (map[string]string, error)

GetElementAttributes получает атрибуты элемента по NodeID

func (*Page) GetElementBox 

func (p *Page) GetElementBox(selector string) (*dom.BoxModel, error)

GetElementBox получает координаты элемента

func (*Page) HumanMouseMove 

func (p *Page) HumanMouseMove(x, y float64) error

HumanMouseMove имитирует человеческое движение мыши

func (*Page) HumanScroll 

func (p *Page) HumanScroll(x, y float64) error

HumanScroll имитирует человеческую прокрутку

func (*Page) KeyEvent 

func (p *Page) KeyEvent(key string) error

KeyEvent отправляет событие нажатия клавиши

func (*Page) MouseClick 

func (p *Page) MouseClick(x, y float64, button input.MouseButton) error

MouseClick выполняет клик мыши по координатам

func (*Page) MouseClickCtrl 

func (p *Page) MouseClickCtrl(x, y float64) error

MouseClickCtrl выполняет Ctrl+Click по координатам (открытие в новой вкладке)

func (*Page) MouseMove 

func (p *Page) MouseMove(x, y float64) error

MouseMove перемещает мышь к координатам

func (*Page) MouseWheel 

func (p *Page) MouseWheel(x, y, deltaY float64) error

MouseWheel прокручивает колесом мыши

func (*Page) Navigate 

func (p *Page) Navigate(url string) error

Navigate переходит по URL

func (*Page) NavigateAndWait 

func (p *Page) NavigateAndWait(url string, waitVisible string) error

NavigateAndWait переходит по URL и ждет загрузки

func (*Page) Nodes 

func (p *Page) Nodes(selector string) ([]*cdp.Node, error)

Nodes получает список узлов DOM по селектору

func (*Page) NodesAll 

func (p *Page) NodesAll(selector string) ([]*cdp.Node, error)

NodesAll получает все узлы DOM по селектору

func (*Page) ReadyState 

func (p *Page) ReadyState() (string, error)

ReadyState получает состояние готовности страницы

func (*Page) Reload 

func (p *Page) Reload() error

Reload перезагружает страницу

func (*Page) RunActions 

func (p *Page) RunActions(actions ...chromedp.Action) error

RunActions выполняет произвольные действия chromedp

func (*Page) Screenshot 

func (p *Page) Screenshot(buf *[]byte) error

Screenshot делает скриншот страницы

func (*Page) ScrollIntoView 

func (p *Page) ScrollIntoView(selector string) error

ScrollIntoView прокручивает страницу к элементу

func (*Page) ScrollPage 

func (p *Page) ScrollPage(scrollDownTimes, scrollUpTimes int) error

ScrollPage прокручивает страницу для загрузки всех элементов

func (*Page) SendKeys 

func (p *Page) SendKeys(selector, text string) error

SendKeys отправляет текст в элемент

func (*Page) SendKeysChar 

func (p *Page) SendKeysChar(selector, text string) error

SendKeysChar отправляет текст посимвольно (имитация человеческого ввода)

func (*Page) SendKeysEnter 

func (p *Page) SendKeysEnter(selector string) error

SendKeysEnter отправляет Enter в элемент

func (*Page) SetGeolocation 

func (p *Page) SetGeolocation(lat, lng float64) error

SetGeolocation устанавливает геолокацию

func (*Page) SetUserAgent 

func (p *Page) SetUserAgent(userAgent, platform string) error

SetUserAgent устанавливает User-Agent и платформу

func (*Page) SetViewport 

func (p *Page) SetViewport(width, height int64, mobile bool) error

SetViewport устанавливает размеры окна просмотра

func (*Page) Text 

func (p *Page) Text(selector string, result *string) error

Text получает текст элемента

func (*Page) Title 

func (p *Page) Title(result *string) error

Title получает заголовок страницы

func (*Page) URL 

func (p *Page) URL(result *string) error

URL получает текущий URL

func (*Page) Value 

func (p *Page) Value(selector string, result *string) error

Value получает значение элемента

func (*Page) WaitForReadyState 

func (p *Page) WaitForReadyState(state string, timeout time.Duration) error

WaitForReadyState ждет определенного состояния готовности страницы

func (*Page) WaitReady 

func (p *Page) WaitReady(selector string) error

WaitReady ждет готовности элемента

func (*Page) WaitVisible 

func (p *Page) WaitVisible(selector string) error

WaitVisible ждет появления элемента

type Tab 

type Tab struct {
	ID       target.ID `json:"id"`
	Type     string    `json:"type"`
	Title    string    `json:"title"`
	URL      string    `json:"url"`
	Attached bool      `json:"attached"`
}

Tab представляет вкладку браузера

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
custom command
remote command
stealth command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.