diff --git a/CHANGELOG.md b/CHANGELOG.md index 0100bb9..6235076 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,64 +9,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - 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 +- CODE_OF_CONDUCT.md following Contributor Covenant +- SECURITY.md with security policy +- This CHANGELOG.md file -## [0.5.0] +## [0.5.0] - 2023 ### Added -- I/O Mode with built-in WebSocket connection support via `cdp.connection` module +- I/O Mode: New `cdp.connection` module with WebSocket I/O support - WebSocket management with async context managers -- JSON-RPC message framing and multiplexing -- Event handling via async iterators +- JSON-RPC message framing +- Command multiplexing +- Event handling with async iterators - Comprehensive error handling with typed exceptions -- Optional websockets dependency via `[io]` extra ### Changed -- Enhanced README with I/O mode documentation -- Improved examples demonstrating both Sans-I/O and I/O modes +- Enhanced documentation with I/O mode examples +- Updated README with usage for both Sans-I/O and I/O modes -## [0.4.0] +## [0.4.x and earlier] -### Changed -- Updated to latest Chrome DevTools Protocol specification -- Improved type hints and mypy compliance -- Enhanced documentation - -## [0.3.0] - -### Added -- Initial Sans-I/O implementation -- Automatic code generation from CDP specification -- Type wrappers for all CDP types, commands, and events -- Comprehensive test suite - -### Changed -- Improved project structure -- Enhanced type safety +### Features +- Sans-I/O mode with type wrappers for Chrome DevTools Protocol +- Auto-generated Python bindings from CDP specification +- Type hints for all CDP commands, events, and types +- Support for all CDP domains +- Documentation on ReadTheDocs +- Example scripts demonstrating CDP usage -## [0.2.0] +--- -### Added -- Enhanced type definitions -- Additional protocol domains - -### Fixed -- Various type annotation improvements -- Bug fixes in code generation - -## [0.1.0] - -### Added -- Initial release -- Basic type wrappers for Chrome DevTools Protocol -- Code generator from CDP specification -- MIT License +For a complete list of changes, see the [commit history](https://github.com/HyperionGray/python-chrome-devtools-protocol/commits/master). [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 +[0.5.0]: https://github.com/HyperionGray/python-chrome-devtools-protocol/releases/tag/v0.5.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 6bf31a2..7969054 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -59,8 +59,9 @@ 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 via GitHub issues. -All complaints will be reviewed and investigated promptly and fairly. +reported to the community leaders responsible for enforcement at the project's +GitHub repository by opening an issue. 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 6b73d26..6ed89a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,138 +1,108 @@ # Contributing to PyCDP -Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! We welcome contributions from the community. +Thank you for your interest in contributing to Python Chrome DevTools Protocol (PyCDP)! This document provides guidelines for contributing to the project. -## Getting Started +## Code of Conduct -### Prerequisites +By participating in this project, you agree to abide by our Code of Conduct (see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)). -- Python 3.7 or higher -- Poetry for dependency management -- Git for version control +## How to Contribute -### Setting Up Development Environment +### Reporting Bugs -1. Fork and clone the repository: - ```bash - git clone https://github.com/YOUR_USERNAME/python-chrome-devtools-protocol.git - cd python-chrome-devtools-protocol - ``` +If you find a bug, please open an issue on GitHub with: +- A clear description of the problem +- Steps to reproduce the issue +- Expected vs. actual behavior +- Your environment (OS, Python version, etc.) -2. Install dependencies: +### Suggesting Enhancements + +Enhancement suggestions are welcome! Please open an issue describing: +- The enhancement you'd like to see +- Why it would be useful +- Any implementation ideas you have + +### Pull Requests + +1. **Fork the repository** and create your branch from `master` +2. **Install development dependencies**: ```bash pip install poetry poetry install ``` +3. **Make your changes** following the project's coding standards +4. **Run tests** to ensure nothing is broken: + ```bash + poetry run make + ``` +5. **Update documentation** if needed +6. **Commit your changes** with clear, descriptive commit messages +7. **Push to your fork** and submit a pull request -## Development Workflow +## Development Setup -### Code Generation +### Prerequisites + +- Python 3.7 or higher +- Poetry for dependency management -This project automatically generates Python wrappers from the Chrome DevTools Protocol specification: +### Installation ```bash -poetry run python generator/generate.py +# Clone the repository +git clone https://github.com/HyperionGray/python-chrome-devtools-protocol.git +cd python-chrome-devtools-protocol + +# Install dependencies +poetry install ``` ### Running Tests -Run the test suite: ```bash +# Run all tests +poetry run make + +# Run specific test suites poetry run pytest test/ poetry run pytest generator/ -``` - -### Type Checking -We use mypy for static type checking: -```bash +# Run type checking poetry run mypy cdp/ poetry run mypy generator/ ``` -### Complete Build +### Code Generation + +This project generates Python code from the Chrome DevTools Protocol specification: -Run all checks (type checking, tests, and generation): ```bash -poetry run make default +poetry run python generator/generate.py ``` -## Submitting Changes - -### Pull Request Process - -1. Create a new branch for your feature or bugfix: - ```bash - git checkout -b feature/your-feature-name - ``` - -2. Make your changes and ensure: - - All tests pass - - Code passes type checking - - Code follows the existing style - - Documentation is updated if needed - -3. Commit your changes with clear, descriptive messages: - ```bash - git commit -m "Add feature: brief description" - ``` - -4. Push to your fork and submit a pull request: - ```bash - git push origin feature/your-feature-name - ``` - -5. In your pull request description: - - Describe what changes you made and why - - Reference any related issues - - Include any relevant context - -### Code Review - -- 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: -- 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 +The generated code is checked into version control. If you modify the generator, run it and include the updated generated files in your PR. -### Feature Requests +## Coding Standards -For feature requests, please: -- Clearly describe the feature and its use case -- Explain why it would be valuable -- Provide examples if possible +- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines +- Use type hints for all functions and methods +- Write docstrings for public APIs +- Ensure code passes `mypy` type checking +- Keep code coverage high -## Code Style +## Project Structure -- 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 +- `cdp/` - Generated CDP protocol bindings +- `generator/` - Code generator for CDP bindings +- `test/` - Test suite +- `docs/` - Documentation source files +- `examples/` - Example usage scripts -## Documentation +## Questions? -- Update README.md if you add new features -- Update docstrings for any modified functions or classes -- Add examples for new functionality when appropriate +If you have questions about contributing, feel free to open an issue or reach out to the maintainers. ## 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! +By contributing to PyCDP, you agree that your contributions will be licensed under the MIT License. diff --git a/LICENSE.md b/LICENSE.md new file mode 120000 index 0000000..7a694c9 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1 @@ +LICENSE \ No newline at end of file diff --git a/README.md b/README.md index 5d9f2d4..2699a7f 100644 --- a/README.md +++ b/README.md @@ -119,4 +119,41 @@ For information about reporting security vulnerabilities, please see our [Securi This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +## API Reference + +The library provides Python wrappers for all Chrome DevTools Protocol domains: + +- **Page**: Page control (navigation, screenshots, etc.) +- **DOM**: DOM inspection and manipulation +- **Network**: Network monitoring and interception +- **Runtime**: JavaScript execution and evaluation +- **Debugger**: JavaScript debugging +- **Performance**: Performance metrics and profiling +- **Security**: Security-related information +- And many more... + +For complete API documentation, visit [py-cdp.readthedocs.io](https://py-cdp.readthedocs.io). + +### Type System + +All CDP types, commands, and events are fully typed with Python type hints, providing: +- IDE autocomplete support +- Static type checking with mypy +- Clear API contracts +- Inline documentation + +## Contributing + +We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on: +- How to report bugs and request features +- Development setup and workflow +- Coding standards and testing requirements +- Pull request process + +For questions or discussions, feel free to open an issue on GitHub. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + define hyperion gray diff --git a/SECURITY.md b/SECURITY.md index b6d758e..b3d11b0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,138 +2,76 @@ ## Supported Versions -We take security seriously and provide security updates for the following versions: +We release patches for security vulnerabilities for the following versions: | Version | Supported | | ------- | ------------------ | | 0.5.x | :white_check_mark: | -| 0.4.x | :white_check_mark: | -| < 0.4 | :x: | +| < 0.5 | :x: | ## Reporting a Vulnerability -If you discover a security vulnerability in PyCDP, please help us by responsibly disclosing it to us. +The PyCDP team takes security bugs seriously. We appreciate your efforts to responsibly disclose your findings. ### How to Report -**Please do not report security vulnerabilities through public GitHub issues.** +To report a security vulnerability, please **do not** open a public GitHub issue. Instead: -Instead, please report security vulnerabilities by: +1. **Email**: Send details to the project maintainers via GitHub by opening a private security advisory at: + https://github.com/HyperionGray/python-chrome-devtools-protocol/security/advisories/new -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 +2. **Include the following information**: + - Description of the vulnerability + - Steps to reproduce the issue + - Potential impact + - Suggested fix (if you have one) + - Your contact information ### 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 +- **Acknowledgment**: We will acknowledge receipt of your vulnerability report within 48 hours +- **Communication**: We will keep you informed about the progress of fixing the vulnerability +- **Timeline**: We aim to release a fix within 30 days of receiving the report +- **Credit**: We will credit you for the discovery in the release notes (unless you prefer to remain anonymous) -- **Restrict access** to CDP endpoints to trusted clients only -- **Use proper authentication** when exposing CDP over a network -- **Monitor connections** for suspicious activity +## Security Best Practices for Users -## Security Considerations +When using PyCDP in your projects: -### 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** +1. **Keep Updated**: Always use the latest version to benefit from security patches +2. **Validate Input**: Sanitize and validate any data sent to the Chrome DevTools Protocol +3. **Network Security**: When connecting to Chrome instances, use secure connections where possible +4. **Least Privilege**: Run Chrome with minimal privileges necessary +5. **Review Dependencies**: Keep all dependencies up to date ## 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 +### WebSocket Connections -## Updates and Patches +PyCDP's I/O mode uses WebSocket connections to communicate with Chrome instances. Be aware: -Security updates will be released as: +- **Authentication**: Chrome DevTools Protocol endpoints typically don't have authentication. Ensure your Chrome instance is not exposed to untrusted networks. +- **Data Exposure**: CDP can execute arbitrary JavaScript and access all page data. Only connect to trusted Chrome instances. +- **Network Security**: Use `ws://localhost` for local development. In production, consider additional network security measures. -- **Patch versions** for critical security fixes -- **GitHub Security Advisories** for documented vulnerabilities -- **CHANGELOG.md** entries for all security-related changes +### Code Execution -Subscribe to repository notifications to stay informed about security updates. +The Chrome DevTools Protocol allows arbitrary JavaScript execution in the browser. When using PyCDP: -## Additional Resources +- Never execute untrusted code through CDP commands +- Validate and sanitize any dynamic content before execution +- Be cautious when using CDP in multi-tenant environments -- [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) +## Disclosure Policy -## Contact +When we receive a security bug report, we will: -For non-security issues, please use GitHub issues. +1. Confirm the problem and determine affected versions +2. Audit code to find similar problems +3. Prepare fixes for all supported versions +4. Release patches as soon as possible +5. Credit the reporter in the release notes -For security concerns, please use the private reporting methods described above. +## Comments on This Policy -Thank you for helping keep PyCDP and its users safe! +If you have suggestions on how this process could be improved, please open an issue or pull request.