diff --git a/CHANGELOG.md b/CHANGELOG.md index cd10141..0100bb9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,75 +5,68 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [0.5.0] - 2024-12-XX +## [Unreleased] ### Added -- **I/O Mode**: New `cdp.connection` module providing WebSocket I/O, JSON-RPC framing, and command multiplexing -- **8 New Domains**: Extensions, FedCm, DeviceAccess, FileSystem, Autofill, BluetoothEmulation, PWA, Preload -- **Privacy Sandbox APIs**: Comprehensive support for Attribution Reporting, Shared Storage, Interest Groups/FLEDGE -- Security-focused APIs for testing federated authentication, device permissions, and extension boundaries -- Bounce tracking mitigation testing capabilities -- IP protection proxy status and control -- Related Website Sets (First-Party Sets) support -- Form security issue detection via Audits domain -- Privacy Sandbox enrollment override for testing -- Enhanced cookie controls for third-party cookie testing +- CONTRIBUTING.md with contribution guidelines +- CHANGELOG.md for tracking version history +- CODE_OF_CONDUCT.md for community standards +- SECURITY.md with security policy and vulnerability reporting + +## [0.5.0] + +### Added +- I/O Mode with built-in WebSocket connection support via `cdp.connection` module +- WebSocket management with async context managers +- JSON-RPC message framing and multiplexing +- Event handling via async iterators +- Comprehensive error handling with typed exceptions +- Optional websockets dependency via `[io]` extra ### Changed -- Updated to Chrome DevTools Protocol version 1.3 (latest) -- Fixed same-domain type reference bug in code generator (e.g., `Network.TimeSinceEpoch` now correctly resolves) -- Improved code generator to protect manually-written files (connection.py, util.py) -- `page.navigate()` now returns 4 values instead of 3 (added `is_download` parameter) +- Enhanced README with I/O mode documentation +- Improved examples demonstrating both Sans-I/O and I/O modes -### Removed -- **Breaking Change**: Removed deprecated Database domain (use IndexedDB, Storage, or Cache Storage APIs instead) +## [0.4.0] -### Security -- Added comprehensive security testing capabilities for Privacy Sandbox -- Enhanced storage domain with privacy-preserving measurement APIs -- Added attribution reporting and shared storage tracking -- Improved form security auditing +### Changed +- Updated to latest Chrome DevTools Protocol specification +- Improved type hints and mypy compliance +- Enhanced documentation -## [0.4.0] - Previous Release +## [0.3.0] ### Added -- Initial sans-I/O implementation -- Type wrappers for Chrome DevTools Protocol +- Initial Sans-I/O implementation - Automatic code generation from CDP specification -- Support for Python 3.7+ - -## Migration Guide - -### From 0.4.x to 0.5.0 +- Type wrappers for all CDP types, commands, and events +- Comprehensive test suite -#### Database Domain Removed -```python -# 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")) -``` - -#### page.navigate() Return Signature Changed -```python -# Old (3 values) -frame_id, loader_id, error_text = await conn.execute(page.navigate(url="...")) +### Changed +- Improved project structure +- Enhanced type safety -# New (4 values - added is_download) -frame_id, loader_id, error_text, is_download = await conn.execute(page.navigate(url="...")) -``` +## [0.2.0] -## Links +### Added +- Enhanced type definitions +- Additional protocol domains -- [Repository](https://github.com/HyperionGray/python-chrome-devtools-protocol) -- [Documentation](https://py-cdp.readthedocs.io) -- [PyPI](https://pypi.org/project/chrome-devtools-protocol/) -- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) +### Fixed +- Various type annotation improvements +- Bug fixes in code generation ---- +## [0.1.0] -For detailed security-relevant updates, see [SECURITY.md](SECURITY.md). -For implementation details, see [IMPLEMENTATION.md](IMPLEMENTATION.md). +### Added +- Initial release +- Basic type wrappers for Chrome DevTools Protocol +- Code generator from CDP specification +- MIT License + +[Unreleased]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.5.0...HEAD +[0.5.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.4.0...v0.5.0 +[0.4.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.3.0...v0.4.0 +[0.3.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.2.0...v0.3.0 +[0.2.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/releases/tag/v0.1.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index b3e66b6..6bf31a2 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -59,8 +59,8 @@ representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at the project -repository. All complaints will be reviewed and investigated promptly and fairly. +reported to the community leaders responsible for enforcement via GitHub issues. +All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ff26a8..6b73d26 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,24 +1,26 @@ # Contributing to PyCDP -Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! This document provides guidelines for contributing to the project. +Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! We welcome contributions from the community. ## Getting Started ### Prerequisites - Python 3.7 or higher -- [Poetry](https://python-poetry.org/) for dependency management +- Poetry for dependency management +- Git for version control -### Setting Up Your Development Environment +### Setting Up Development Environment -1. Fork the repository on GitHub -2. Clone your fork locally: +1. Fork and clone the repository: ```bash git clone https://github.com/YOUR_USERNAME/python-chrome-devtools-protocol.git cd python-chrome-devtools-protocol ``` -3. Install dependencies: + +2. Install dependencies: ```bash + pip install poetry poetry install ``` @@ -26,118 +28,111 @@ Thank you for your interest in contributing to Python Chrome DevTools Protocol ( ### Code Generation -This project automatically generates Python wrappers from the Chrome DevTools Protocol specification. Most code in the `cdp/` directory (except `connection.py` and `util.py`) is auto-generated. +This project automatically generates Python wrappers from the Chrome DevTools Protocol specification: -To regenerate the protocol wrappers: ```bash -poetry run make generate +poetry run python generator/generate.py ``` ### Running Tests Run the test suite: ```bash -poetry run make test-cdp -poetry run make test-generate -``` - -Or run all checks: -```bash -poetry run make +poetry run pytest test/ +poetry run pytest generator/ ``` ### Type Checking We use mypy for static type checking: ```bash -poetry run make mypy-cdp -poetry run make mypy-generate +poetry run mypy cdp/ +poetry run mypy generator/ ``` -### Building Documentation +### Complete Build -To build the documentation: +Run all checks (type checking, tests, and generation): ```bash -poetry run make docs +poetry run make default ``` -## Making Changes - -### Code Style +## Submitting Changes -- Follow PEP 8 style guidelines -- Use type hints for all function signatures -- Keep code clear and well-documented - -### Commit Messages - -- Use clear and descriptive commit messages -- Reference issue numbers when applicable -- Keep commits focused on a single change +### Pull Request Process -### Pull Requests - -1. Create a new branch for your changes: +1. Create a new branch for your feature or bugfix: ```bash git checkout -b feature/your-feature-name ``` -2. Make your changes and commit them -3. Push to your fork and submit a pull request -4. Ensure all tests pass and type checking succeeds -5. Provide a clear description of your changes - -## What to Contribute -### Areas for Contribution +2. Make your changes and ensure: + - All tests pass + - Code passes type checking + - Code follows the existing style + - Documentation is updated if needed -- **Bug fixes**: Fix issues in the connection module or utility functions -- **Documentation**: Improve examples, tutorials, or API documentation -- **Tests**: Add test coverage for existing functionality -- **Examples**: Add new usage examples in the `examples/` directory +3. Commit your changes with clear, descriptive messages: + ```bash + git commit -m "Add feature: brief description" + ``` -### Code Generation Changes +4. Push to your fork and submit a pull request: + ```bash + git push origin feature/your-feature-name + ``` -If you need to modify code generation: -- Edit files in the `generator/` directory -- Run the generator and verify the output -- Ensure all tests still pass -- Add tests for your generator changes +5. In your pull request description: + - Describe what changes you made and why + - Reference any related issues + - Include any relevant context -### Protocol Updates +### Code Review -The protocol definitions are automatically fetched from the Chrome DevTools Protocol repository. If you need to update to a newer protocol version, please open an issue first to discuss the change. +- Maintainers will review your pull request +- Address any feedback or requested changes +- Once approved, a maintainer will merge your PR ## Reporting Issues ### Bug Reports When reporting bugs, please include: -- Python version -- PyCDP version -- Steps to reproduce -- Expected vs. actual behavior -- Error messages or stack traces +- A clear, descriptive title +- Steps to reproduce the issue +- Expected behavior vs. actual behavior +- Python version and environment details +- Any relevant error messages or logs ### Feature Requests -For feature requests: -- Clearly describe the feature -- Explain the use case -- Consider if it fits the project's scope +For feature requests, please: +- Clearly describe the feature and its use case +- Explain why it would be valuable +- Provide examples if possible -## Code of Conduct +## Code Style -Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for all contributors. +- Follow PEP 8 style guidelines +- Use type hints for function parameters and return values +- Write clear, descriptive variable and function names +- Add docstrings for public APIs +- Keep functions focused and modular -## Questions? +## Documentation -If you have questions about contributing, please: -- Check existing issues and pull requests -- Open a new issue with your question -- Tag it appropriately for visibility +- Update README.md if you add new features +- Update docstrings for any modified functions or classes +- Add examples for new functionality when appropriate ## License -By contributing to PyCDP, you agree that your contributions will be licensed under the MIT License. +By contributing, you agree that your contributions will be licensed under the MIT License. + +## Questions? + +If you have questions, feel free to: +- Open an issue for discussion +- Reach out to the maintainers Thank you for contributing to PyCDP! diff --git a/README.md b/README.md index fb71eb1..5d9f2d4 100644 --- a/README.md +++ b/README.md @@ -86,62 +86,34 @@ frame_id = page.FrameId('my id') assert repr(frame_id) == "FrameId('my id')" ``` -## API Reference +## API Documentation -PyCDP provides Python wrappers for all Chrome DevTools Protocol domains. Here are some commonly used domains: +For detailed API documentation, see: -### Core Domains -- **`cdp.page`** - Page navigation, lifecycle, and screenshot capabilities -- **`cdp.network`** - Network request/response monitoring and modification -- **`cdp.runtime`** - JavaScript runtime interaction and evaluation -- **`cdp.dom`** - DOM tree inspection and manipulation -- **`cdp.debugger`** - JavaScript debugging capabilities +- **[Complete Documentation](https://py-cdp.readthedocs.io)** - Full API reference on Read the Docs +- **[Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)** - Official CDP specification +- **[Examples](examples/)** - Code examples demonstrating usage patterns -### Browser Control -- **`cdp.browser`** - Browser-level operations and window management -- **`cdp.target`** - Target (tab/page) creation and management -- **`cdp.emulation`** - Device emulation and viewport control -- **`cdp.input_`** - Input event simulation (mouse, keyboard, touch) +### Key Modules -### Monitoring & Analysis -- **`cdp.performance`** - Performance metrics and profiling -- **`cdp.console`** - Console message handling -- **`cdp.log`** - Log entry handling -- **`cdp.tracing`** - Chrome tracing for performance analysis - -### Storage & Security -- **`cdp.storage`** - Storage management (cookies, cache, IndexedDB, Privacy Sandbox) -- **`cdp.security`** - Security state and certificate information -- **`cdp.audits`** - Automated security and privacy issue detection -- **`cdp.fetch`** - Network request interception and modification - -### Advanced Features -- **`cdp.extensions`** - Browser extension management and testing -- **`cdp.fed_cm`** - Federated Credential Management (FedCM) testing -- **`cdp.device_access`** - Device permission prompt handling -- **`cdp.web_authn`** - WebAuthn virtual authenticator support - -For complete API documentation, see the [full documentation](https://py-cdp.readthedocs.io). - -## Examples - -Check the [examples directory](examples/) for practical usage examples. +- `cdp.connection` - WebSocket I/O and connection management (I/O mode) +- `cdp.` - Type wrappers for each CDP domain (e.g., `cdp.page`, `cdp.network`, `cdp.runtime`) +- Each domain module provides types, commands, and events for that CDP domain ## Contributing -We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on: -## Security - -For security-related matters, please see [SECURITY.md](SECURITY.md). +- Setting up your development environment +- Running tests and type checking +- Submitting pull requests +- Reporting issues -## Changelog +Please also read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing. -See [CHANGELOG.md](CHANGELOG.md) for version history and migration guides. - -## Documentation +## Security -For more information, see the [complete documentation](https://py-cdp.readthedocs.io). +For information about reporting security vulnerabilities, please see our [Security Policy](SECURITY.md). ## License diff --git a/SECURITY.md b/SECURITY.md index 05faee8..b6d758e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,267 +1,139 @@ # Security Policy -## Reporting Security Vulnerabilities +## Supported Versions -If you discover a security vulnerability in PyCDP, please report it by: +We take security seriously and provide security updates for the following versions: -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) +| Version | Supported | +| ------- | ------------------ | +| 0.5.x | :white_check_mark: | +| 0.4.x | :white_check_mark: | +| < 0.4 | :x: | -We will respond to security reports within 48 hours and work with you to address the issue promptly. +## Reporting a Vulnerability -## Security Scanning Setup +If you discover a security vulnerability in PyCDP, please help us by responsibly disclosing it to us. -For information on setting up automated security scanning for this project, see [SECURITY_SETUP.md](SECURITY_SETUP.md). +### How to Report -## Supported Versions +**Please do not report security vulnerabilities through public GitHub issues.** -We provide security updates for the following versions: +Instead, please report security vulnerabilities by: -| Version | Supported | -| ------- | ------------------ | -| 0.5.x | :white_check_mark: | -| < 0.5 | :x: | - ---- - -# Security-Relevant API Updates - -This document highlights the security-relevant additions to the Chrome DevTools Protocol implementation in this update. - -## Summary - -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. - -## New Security-Focused Domains - -### 1. Extensions Domain -**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 - -### 2. FedCm Domain (Federated Credential Management) -**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 - -### 3. DeviceAccess Domain -**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 - -### 4. FileSystem Domain -**Purpose**: File system directory access -- Get directory access for testing File System Access API -- **Use Case**: Test file system permission boundaries - -### 5. Autofill, BluetoothEmulation, PWA, Preload Domains -Additional domains for comprehensive browser testing - -## Major Security Updates to Existing Domains - -### Storage Domain - Privacy Sandbox APIs -The Storage domain received the most significant security-relevant updates: - -#### Attribution Reporting API (Privacy-Preserving Ad Measurement) -```python -# 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}") -``` - -#### Shared Storage API (Cross-Site Storage with Privacy) -```python -# 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" -)) -``` - -#### Interest Groups / FLEDGE / Protected Audience API -```python -# 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)) -``` - -#### Bounce Tracking Mitigation -```python -# Test bounce tracking mitigation -deleted_sites = await conn.execute(storage.run_bounce_tracking_mitigations()) -print(f"Mitigated tracking for {len(deleted_sites)} sites") -``` - -### Network Domain - Cookie and IP Protection -```python -# 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()) -``` - -### Audits Domain - Form Security -```python -# Automated form security/privacy issue detection -issues = await conn.execute(audits.check_forms_issues()) -for issue in issues: - print(f"Form issue detected: {issue}") -``` - -### Browser Domain - Privacy Sandbox Configuration -```python -# 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" -)) -``` - -## Security Testing Use Cases - -### 1. Privacy Sandbox Testing -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 - -### 2. Third-Party Cookie Migration -Test alternatives to third-party cookies: -- First-Party Sets (Related Website Sets) -- Partitioned cookies (CHIPS) -- Storage Access API -- Cookie controls and policies - -### 3. Authentication Security -- Test FedCm federated login flows -- Verify account selection security -- Test dialog dismissal handling - -### 4. Permission Testing -- Verify device permission prompts (camera, mic, etc.) -- Test permission grant/deny flows -- Validate permission persistence - -### 5. Extension Security -- Test extension isolation boundaries -- Verify extension data access controls -- Test extension installation/uninstallation - -### 6. Anti-Tracking Features -- Test bounce tracking mitigation -- Verify IP protection -- Test tracking prevention measures - -### 7. Form Security Auditing -- Automated detection of insecure forms -- Privacy leak detection -- Input validation issues - -## Breaking Changes - -**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`) - -## Implementation Notes - -### Generator Improvements -- 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 - -### Testing -- All 19 tests passing -- mypy type checking successful (56 modules) -- Generator tests updated and passing (20 tests) - -## Migration Guide - -### For Users of cdp.database -```python -# 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")) -``` - -### For page.navigate() Users -```python -# 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="...")) -``` - -## References - -- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) -- [Privacy Sandbox APIs](https://privacysandbox.com/) -- [Attribution Reporting API](https://github.com/WICG/attribution-reporting-api) -- [Shared Storage API](https://github.com/WICG/shared-storage) -- [FLEDGE/Protected Audience](https://github.com/WICG/turtledove) -- [FedCM](https://fedidcg.github.io/FedCM/) - -## Examples - -For practical examples demonstrating the security-focused APIs, see the [examples directory](examples/) and the usage examples throughout this document. - -You can also refer to the [Chrome DevTools Protocol documentation](https://chromedevtools.github.io/devtools-protocol/) for additional examples and specifications. - -## Version Information - -- 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) +1. **Creating a private security advisory** on GitHub: + - Go to the [Security tab](https://github.com/HyperionGray/python-chrome-devtools-protocol/security) + - Click "Report a vulnerability" + - Provide detailed information about the vulnerability + +2. **Or by emailing** the maintainers directly: + - Include "SECURITY" in the subject line + - Provide a detailed description of the vulnerability + - Include steps to reproduce the issue + - Suggest a fix if possible + +### What to Include + +When reporting a vulnerability, please include: + +- Type of vulnerability (e.g., injection, XSS, authentication bypass) +- Full paths of source file(s) related to the vulnerability +- Location of the affected source code (tag/branch/commit or direct URL) +- Step-by-step instructions to reproduce the issue +- Proof-of-concept or exploit code (if possible) +- Impact of the vulnerability and potential attack scenarios + +### What to Expect + +- **Initial Response**: We aim to acknowledge receipt within 48 hours +- **Status Updates**: We'll keep you informed about our progress +- **Disclosure Timeline**: We'll work with you to understand the issue and develop a fix +- **Credit**: We'll acknowledge your contribution in release notes (unless you prefer to remain anonymous) + +## Security Best Practices + +When using PyCDP: + +### WebSocket Connections + +- **Always use TLS/SSL** for WebSocket connections in production (`wss://` not `ws://`) +- **Validate endpoint URLs** before connecting +- **Authenticate connections** properly to Chrome DevTools endpoints +- **Limit exposure** of CDP endpoints (use `--remote-debugging-port` carefully) + +### Input Validation + +- **Sanitize inputs** when sending commands to Chrome DevTools +- **Validate responses** from the browser +- **Handle errors gracefully** to prevent information disclosure + +### Dependency Management + +- **Keep dependencies up to date** using `poetry update` +- **Review security advisories** for dependencies +- **Use the optional `[io]` extra** only when needed to minimize dependency surface + +### Access Control + +- **Restrict access** to CDP endpoints to trusted clients only +- **Use proper authentication** when exposing CDP over a network +- **Monitor connections** for suspicious activity + +## Security Considerations + +### Chrome DevTools Protocol + +The Chrome DevTools Protocol provides powerful control over browser instances: + +- **Full DOM access**: Can read and modify page content +- **JavaScript execution**: Can execute arbitrary JavaScript in pages +- **Network interception**: Can intercept and modify network requests +- **Cookie access**: Can read and modify cookies +- **Storage access**: Can read and modify localStorage, sessionStorage, etc. + +### Important Warnings + +⚠️ **Never expose CDP endpoints to untrusted networks without authentication** + +⚠️ **Be cautious when connecting to untrusted CDP endpoints** + +⚠️ **Validate all data received from CDP to prevent injection attacks** + +⚠️ **Do not store sensitive credentials in CDP commands or scripts** + +## Known Security Considerations + +### WebSocket Security + +- WebSocket connections do not follow same-origin policy +- Ensure proper origin validation for CDP endpoints +- Use secure WebSocket connections (WSS) in production + +### Code Execution + +- CDP allows arbitrary JavaScript execution +- Validate and sanitize any user input before executing +- Be aware of potential for remote code execution vulnerabilities + +## Updates and Patches + +Security updates will be released as: + +- **Patch versions** for critical security fixes +- **GitHub Security Advisories** for documented vulnerabilities +- **CHANGELOG.md** entries for all security-related changes + +Subscribe to repository notifications to stay informed about security updates. + +## Additional Resources + +- [Chrome DevTools Protocol Documentation](https://chromedevtools.github.io/devtools-protocol/) +- [OWASP WebSocket Security](https://owasp.org/www-community/vulnerabilities/WebSocket_Security) +- [Python Security Best Practices](https://python.readthedocs.io/en/stable/library/security_warnings.html) + +## Contact + +For non-security issues, please use GitHub issues. + +For security concerns, please use the private reporting methods described above. + +Thank you for helping keep PyCDP and its users safe!