Agent skill

browser-automation

Expert in browser automation using Chrome DevTools Protocol (CDP) and WebDriver. Specializes in secure web automation, testing, and scraping with proper credential handling, domain restrictions, and audit logging. HIGH-RISK skill due to web access and data handling.

Stars 32
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/martinholovsky/claude-skills-generator/tree/main/skills/browser-automation

SKILL.md

1. Overview

Risk Level: HIGH - Web access, credential handling, data extraction, network requests

You are an expert in browser automation with deep expertise in:

  • Chrome DevTools Protocol: Direct Chrome/Chromium control
  • WebDriver/Selenium: Cross-browser automation standard
  • Playwright/Puppeteer: Modern automation frameworks
  • Security Controls: Domain restrictions, credential protection

Core Principles

  1. TDD First - Write tests before implementation using pytest-playwright
  2. Performance Aware - Reuse contexts, parallelize, block unnecessary resources
  3. Security First - Domain allowlists, credential protection, audit logging
  4. Reliable Automation - Timeout enforcement, proper waits, error handling

Core Expertise Areas

  1. CDP Protocol: Network interception, DOM manipulation, JavaScript execution
  2. WebDriver API: Element interaction, navigation, waits
  3. Security: Domain allowlists, credential handling, audit logging
  4. Performance: Resource management, parallel execution

2. Implementation Workflow (TDD)

Step 1: Write Failing Test First

python
# tests/test_browser_automation.py
import pytest
from playwright.sync_api import Page, expect

class TestSecureBrowserAutomation:
    """Test secure browser automation with pytest-playwright."""

    def test_blocks_banking_domains(self, automation):
        """Test that banking domains are blocked."""
        with pytest.raises(SecurityError, match="URL blocked"):
            automation.navigate("https://chase.com")

    def test_allows_permitted_domains(self, automation):
        """Test navigation to allowed domains."""
        automation.navigate("https://example.com")
        assert "Example" in automation.page.title()

    def test_blocks_password_fields(self, automation):
        """Test that password field filling is blocked."""
        automation.navigate("https://example.com/form")
        with pytest.raises(SecurityError, match="password"):
            automation.fill('input[type="password"]', "secret")

    def test_rate_limiting_enforced(self, automation):
        """Test rate limiting prevents abuse."""
        for _ in range(60):
            automation.check_request()
        with pytest.raises(RateLimitError):
            automation.check_request()

@pytest.fixture
def automation():
    """Provide configured SecureBrowserAutomation instance."""
    auto = SecureBrowserAutomation(
        domain_allowlist=['example.com'],
        permission_tier='standard'
    )
    auto.start_session()
    yield auto
    auto.close()

Step 2: Implement Minimum to Pass

python
# Implement just enough to pass tests
class SecureBrowserAutomation:
    def navigate(self, url: str):
        if not self._validate_url(url):
            raise SecurityError(f"URL blocked: {url}")
        self.page.goto(url)

Step 3: Refactor Following Patterns

After tests pass, refactor to add:

  • Proper error handling
  • Audit logging
  • Performance optimizations

Step 4: Run Full Verification

bash
# Run all browser automation tests
pytest tests/test_browser_automation.py -v --headed

# Run with coverage
pytest tests/test_browser_automation.py --cov=src/automation --cov-report=term-missing

# Run security-specific tests
pytest tests/test_browser_automation.py -k "security" -v

3. Performance Patterns

Pattern 1: Browser Context Reuse

python
# BAD - Creates new browser for each test
def test_page_one():
    browser = playwright.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com/one")
    browser.close()

def test_page_two():
    browser = playwright.chromium.launch()  # Slow startup again
    page = browser.new_page()
    page.goto("https://example.com/two")
    browser.close()

# GOOD - Reuse browser context
@pytest.fixture(scope="session")
def browser():
    """Share browser across all tests in session."""
    pw = sync_playwright().start()
    browser = pw.chromium.launch()
    yield browser
    browser.close()
    pw.stop()

@pytest.fixture
def page(browser):
    """Create fresh context per test for isolation."""
    context = browser.new_context()
    page = context.new_page()
    yield page
    context.close()

Pattern 2: Parallel Execution

python
# BAD - Sequential scraping
def scrape_all(urls: list) -> list:
    results = []
    for url in urls:
        page.goto(url)
        results.append(page.content())
    return results  # Very slow for many URLs

# GOOD - Parallel with multiple contexts
def scrape_all_parallel(urls: list, browser, max_workers: int = 4) -> list:
    """Scrape URLs in parallel using multiple contexts."""
    from concurrent.futures import ThreadPoolExecutor, as_completed

    def scrape_url(url: str) -> str:
        context = browser.new_context()
        page = context.new_page()
        try:
            page.goto(url, wait_until='domcontentloaded')
            return page.content()
        finally:
            context.close()

    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        futures = {executor.submit(scrape_url, url): url for url in urls}
        return [future.result() for future in as_completed(futures)]

Pattern 3: Network Interception for Speed

python
# BAD - Load all resources
page.goto("https://example.com")  # Loads images, fonts, analytics

# GOOD - Block unnecessary resources
def setup_resource_blocking(page):
    """Block resources that slow down automation."""
    page.route("**/*", lambda route: (
        route.abort() if route.request.resource_type in [
            "image", "media", "font", "stylesheet"
        ] else route.continue_()
    ))

# Usage
setup_resource_blocking(page)
page.goto("https://example.com")  # 2-3x faster

Pattern 4: Request Blocking for Analytics

python
# BAD - Allow all tracking requests
page.goto(url)  # Slow due to analytics loading

# GOOD - Block tracking domains
BLOCKED_DOMAINS = [
    '*google-analytics.com*',
    '*googletagmanager.com*',
    '*facebook.com/tr*',
    '*doubleclick.net*',
]

def setup_tracking_blocker(page):
    """Block tracking and analytics requests."""
    for pattern in BLOCKED_DOMAINS:
        page.route(pattern, lambda route: route.abort())

# Apply before navigation
setup_tracking_blocker(page)
page.goto(url)  # Faster, no tracking overhead

Pattern 5: Efficient Selectors

python
# BAD - Slow selectors
page.locator("//div[@class='container']//span[contains(text(), 'Submit')]").click()
page.wait_for_selector(".dynamic-content", timeout=30000)

# GOOD - Fast, specific selectors
page.locator("[data-testid='submit-button']").click()  # Direct attribute
page.locator("#unique-id").click()  # ID is fastest

# GOOD - Use role selectors for accessibility
page.get_by_role("button", name="Submit").click()
page.get_by_label("Email").fill("test@example.com")

# GOOD - Combine selectors for specificity without XPath
page.locator("form.login >> button[type='submit']").click()

4. Core Responsibilities

4.1 Safe Automation Principles

When automating browsers:

  • Restrict domains to allowlist
  • Never store credentials in scripts
  • Block sensitive URLs (banking, healthcare)
  • Log all navigations and actions
  • Implement timeouts on all operations

4.2 Security-First Approach

Every browser operation MUST:

  1. Validate URL against domain allowlist
  2. Check for credential exposure
  3. Block sensitive site access
  4. Log operation details
  5. Enforce timeout limits

4.3 Data Handling

  • Never extract credentials from pages
  • Redact sensitive data in logs
  • Clear browser state after sessions
  • Use isolated profiles

5. Technical Foundation

5.1 Automation Frameworks

Chrome DevTools Protocol (CDP):

  • Direct browser control
  • Network interception
  • Performance profiling

WebDriver/Selenium:

  • Cross-browser support
  • W3C standard

Modern Frameworks:

  • Playwright: Multi-browser, auto-waiting
  • Puppeteer: CDP wrapper for Chrome

5.2 Security Considerations

Risk Area Mitigation Priority
Credential theft Domain allowlists CRITICAL
Phishing URL validation CRITICAL
Data exfiltration Output filtering HIGH
Session hijacking Isolated profiles HIGH

6. Implementation Patterns

Pattern 1: Secure Browser Session

python
from playwright.sync_api import sync_playwright
import logging
import re
from urllib.parse import urlparse

class SecureBrowserAutomation:
    """Secure browser automation with comprehensive controls."""

    BLOCKED_DOMAINS = {
        'chase.com', 'bankofamerica.com', 'wellsfargo.com',
        'accounts.google.com', 'login.microsoft.com',
        'paypal.com', 'venmo.com', 'stripe.com',
    }

    BLOCKED_URL_PATTERNS = [
        r'/login', r'/signin', r'/auth', r'/password',
        r'/payment', r'/checkout', r'/billing',
    ]

    def __init__(self, domain_allowlist: list = None, permission_tier: str = 'standard'):
        self.domain_allowlist = domain_allowlist
        self.permission_tier = permission_tier
        self.logger = logging.getLogger('browser.security')
        self.timeout = 30000

    def start_session(self):
        """Start browser with security settings."""
        self.playwright = sync_playwright().start()
        self.browser = self.playwright.chromium.launch(
            headless=True,
            args=['--disable-extensions', '--disable-plugins', '--no-sandbox']
        )
        self.context = self.browser.new_context(ignore_https_errors=False)
        self.context.set_default_timeout(self.timeout)
        self.page = self.context.new_page()

    def navigate(self, url: str):
        """Navigate with URL validation."""
        if not self._validate_url(url):
            raise SecurityError(f"URL blocked: {url}")
        self._audit_log('navigate', url)
        self.page.goto(url, wait_until='networkidle')

    def _validate_url(self, url: str) -> bool:
        """Validate URL against security rules."""
        parsed = urlparse(url)
        domain = parsed.netloc.lower().removeprefix('www.')
        if any(domain == d or domain.endswith('.' + d) for d in self.BLOCKED_DOMAINS):
            return False
        if self.domain_allowlist:
            if not any(domain == d or domain.endswith('.' + d) for d in self.domain_allowlist):
                return False
        return not any(re.search(p, url, re.I) for p in self.BLOCKED_URL_PATTERNS)

    def close(self):
        """Clean up browser session."""
        if hasattr(self, 'context'):
            self.context.clear_cookies()
            self.context.close()
        if hasattr(self, 'browser'):
            self.browser.close()
        if hasattr(self, 'playwright'):
            self.playwright.stop()

Pattern 2: Rate Limiting

python
import time

class BrowserRateLimiter:
    """Rate limit browser operations."""

    def __init__(self, requests_per_minute: int = 60):
        self.requests_per_minute = requests_per_minute
        self.request_times = []

    def check_request(self):
        """Check if request is allowed."""
        cutoff = time.time() - 60
        self.request_times = [t for t in self.request_times if t > cutoff]
        if len(self.request_times) >= self.requests_per_minute:
            raise RateLimitError("Request rate limit exceeded")
        self.request_times.append(time.time())

7. Security Standards

7.1 Critical Vulnerabilities

Vulnerability CWE Severity Mitigation
XSS via Automation CWE-79 HIGH Sanitize injected scripts
Credential Harvesting CWE-522 CRITICAL Block password field access
Session Hijacking CWE-384 HIGH Isolated profiles, session clearing
Phishing Automation CWE-601 CRITICAL Domain allowlists, URL validation

7.2 Common Mistakes

python
# Never: Fill Password Fields
# BAD
page.fill('input[type="password"]', password)

# GOOD
if element.get_attribute('type') == 'password':
    raise SecurityError("Cannot fill password fields")

# Never: Access Banking Sites
# BAD
page.goto(user_url)

# GOOD
if not validate_url(user_url):
    raise SecurityError("URL blocked")
page.goto(user_url)

8. Pre-Implementation Checklist

Before Writing Code

  • Read security requirements from PRD Section 8
  • Write failing tests for new automation features
  • Define domain allowlist for target sites
  • Identify sensitive elements to block/redact

During Implementation

  • Implement URL validation before navigation
  • Add audit logging for all actions
  • Configure request interception and blocking
  • Set appropriate timeouts for all operations
  • Reuse browser contexts for performance

Before Committing

  • All tests pass: pytest tests/test_browser_automation.py
  • Security tests pass: pytest -k security
  • No credentials in code or logs
  • Session cleanup verified
  • Rate limiting configured and tested

9. Summary

Your goal is to create browser automation that is:

  • Test-Driven: Write tests first, implement to pass
  • Performant: Context reuse, parallelization, resource blocking
  • Secure: Domain restrictions, credential protection, output filtering
  • Auditable: Comprehensive logging, request tracking

Implementation Order:

  1. Write failing test first
  2. Implement minimum code to pass
  3. Refactor with performance patterns
  4. Run all verification commands
  5. Commit only when all pass

References

  • See references/secure-session-full.md - Complete SecureBrowserAutomation class
  • See references/security-examples.md - Additional security patterns
  • See references/threat-model.md - Full threat analysis

Expand your agent's capabilities with these related and highly-rated skills.

martinholovsky/claude-skills-generator

prompt-engineering

Expert skill for prompt engineering and task routing/orchestration. Covers secure prompt construction, injection prevention, multi-step task orchestration, and LLM output validation for JARVIS AI assistant.

32 3
Explore
martinholovsky/claude-skills-generator

windows-ui-automation

Expert in Windows UI Automation (UIA) and Win32 APIs for desktop automation. Specializes in accessible, secure automation of Windows applications including element discovery, input simulation, and process interaction. HIGH-RISK skill requiring strict security controls for system access.

32 3
Explore
martinholovsky/claude-skills-generator

accessibility-wcag

32 3
Explore
martinholovsky/claude-skills-generator

devsecops-expert

Expert DevSecOps engineer specializing in secure CI/CD pipelines, shift-left security, security automation, and compliance as code. Use when implementing security gates, container security, infrastructure scanning, secrets management, or building secure supply chains.

32 3
Explore
martinholovsky/claude-skills-generator

kanidm-expert

Expert in Kanidm modern identity management system specializing in user/group management, OAuth2/OIDC, LDAP, RADIUS, SSH key management, WebAuthn, and MFA. Deep expertise in secure authentication flows, credential policies, access control, and platform integrations. Use when implementing identity management, SSO, authentication systems, or securing access to infrastructure.

32 3
Explore
martinholovsky/claude-skills-generator

motion-design

32 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results