If you discover a security vulnerability in PyCDP, please report it by:

1. Do NOT open a public issue
2. Email the maintainers directly (see repository for contact information)
3. Include detailed information about the vulnerability:
   • Description of the issue
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if available)

We will respond to security reports within 48 hours and work with you to address the issue promptly.

For information on setting up automated security scanning for this project, see SECURITY_SETUP.md.

We provide security updates for the following versions:

This document highlights the security-relevant additions to the Chrome DevTools Protocol implementation in this update.

This update brings the python-chrome-devtools-protocol library to the latest CDP specification, adding 8 new domains and significantly expanding security-relevant APIs, particularly in the Privacy Sandbox area.

Purpose: Browser extension management for security testing

• Load and uninstall extensions programmatically
• Manage extension storage (local/sync/managed)
• Use Case: Test extension security boundaries, data isolation, and permission handling

Purpose: Test federated authentication flows

• Track and interact with FedCm dialogs
• Programmatically select accounts or dismiss dialogs
• Use Case: Verify federated login security, test account selection flows

Purpose: Handle device permission prompts

• Track camera, microphone, and other device access requests
• Programmatically grant or deny permissions
• Use Case: Test device permission security, verify proper permission prompts

Purpose: File system directory access

• Get directory access for testing File System Access API
• Use Case: Test file system permission boundaries

Additional domains for comprehensive browser testing

The Storage domain received the most significant security-relevant updates:

# Enable tracking and local testing
await conn.execute(storage.set_attribution_reporting_tracking(enable=True))
await conn.execute(storage.set_attribution_reporting_local_testing_mode(enabled=True))

# Send test reports
await conn.execute(storage.send_pending_attribution_reports())

# Listen for events
async for event in conn.listen():
    if isinstance(event, storage.AttributionReportingSourceRegistered):
        print(f"Source registered: {event.registration}")

# Track shared storage access
await conn.execute(storage.set_shared_storage_tracking(enable=True))

# Get and set entries for testing
metadata = await conn.execute(storage.get_shared_storage_metadata(
    owner_origin="https://example.com"
))

await conn.execute(storage.set_shared_storage_entry(
    owner_origin="https://example.com",
    key="test-key",
    value="test-value"
))

# Track interest group auctions
await conn.execute(storage.set_interest_group_tracking(enable=True))
await conn.execute(storage.set_interest_group_auction_tracking(enable=True))

# Get details for security verification
details = await conn.execute(storage.get_interest_group_details(
    owner_origin="https://example.com",
    name="interest-group-name"
))

# Configure k-anonymity for testing
await conn.execute(storage.set_protected_audience_k_anonymity(threshold=50))

# Test bounce tracking mitigation
deleted_sites = await conn.execute(storage.run_bounce_tracking_mitigations())
print(f"Mitigated tracking for {len(deleted_sites)} sites")

# Control cookie behavior for third-party cookie testing
await conn.execute(network.set_cookie_controls(mode='block-third-party'))

# Test IP protection features
status = await conn.execute(network.get_ip_protection_proxy_status())
await conn.execute(network.set_ip_protection_proxy_bypass_enabled(enabled=True))

# Get related website sets (First-Party Sets)
sets = await conn.execute(storage.get_related_website_sets())

# Automated form security/privacy issue detection
issues = await conn.execute(audits.check_forms_issues())
for issue in issues:
    print(f"Form issue detected: {issue}")

# Override Privacy Sandbox enrollment for testing
await conn.execute(browser.add_privacy_sandbox_enrollment_override(
    url="https://example.com"
))

# Configure coordinator keys
await conn.execute(browser.add_privacy_sandbox_coordinator_key_config(
    coordinator_origin="https://coordinator.example.com",
    coordinator_key="test-key"
))

Test the complete Privacy Sandbox suite:

• Attribution Reporting (privacy-preserving conversion measurement)
• Shared Storage (cross-site storage with privacy guarantees)
• Interest Groups/FLEDGE (privacy-preserving ad auctions)
• Topics API (via interest groups)
• k-anonymity thresholds

Test alternatives to third-party cookies:

• First-Party Sets (Related Website Sets)
• Partitioned cookies (CHIPS)
• Storage Access API
• Cookie controls and policies

• Test FedCm federated login flows
• Verify account selection security
• Test dialog dismissal handling

• Verify device permission prompts (camera, mic, etc.)
• Test permission grant/deny flows
• Validate permission persistence

• Test extension isolation boundaries
• Verify extension data access controls
• Test extension installation/uninstallation

• Test bounce tracking mitigation
• Verify IP protection
• Test tracking prevention measures

• Automated detection of insecure forms
• Privacy leak detection
• Input validation issues

Database Domain Removed: The deprecated Database domain has been removed from the CDP specification. If your code imports cdp.database, you must migrate to:

• IndexedDB APIs (cdp.indexed_db)
• Storage APIs (cdp.storage)
• Cache Storage APIs (cdp.cache_storage)

• Fixed same-domain type reference bug (e.g., Network.TimeSinceEpoch now correctly resolves to TimeSinceEpoch within the network module)
• Added domain context to all type, command, and event generation
• Protected manually-written files (connection.py, util.py) from deletion

• All 19 tests passing
• mypy type checking successful (56 modules)
• Generator tests updated and passing (20 tests)

# Old (no longer works)
from cdp import database
await conn.execute(database.some_command())

# New - Use IndexedDB instead
from cdp import indexed_db
await conn.execute(indexed_db.request_database_names(security_origin="https://example.com"))

# Old return signature (3 values)
frame_id, loader_id, error_text = await conn.execute(page.navigate(url="..."))

# New return signature (4 values - added isDownload)
frame_id, loader_id, error_text, is_download = await conn.execute(page.navigate(url="..."))

• Chrome DevTools Protocol
• Privacy Sandbox APIs
• Attribution Reporting API
• Shared Storage API
• FLEDGE/Protected Audience
• FedCM

For practical examples demonstrating the security-focused APIs, see the examples directory and the usage examples throughout this document.

You can also refer to the Chrome DevTools Protocol documentation for additional examples and specifications.

• Protocol Version: 1.3 (latest)
• Total Domains: 56 (up from 48)
• New Domains: 8
• Removed Domains: 1 (Database)
• Security-Relevant Updates: 5 domains (Storage, Network, Audits, Browser, Target)