diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..805d579 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,79 @@ +name: Bug report +description: Report a bug in the invisible_playwright Python wrapper +title: "[bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. + + Before continuing, please: + - Search [existing issues](https://github.com/feder-cr/invisible_playwright/issues?q=is%3Aissue) to avoid duplicates. + - If the bug is in the **patched Firefox itself** (canvas/WebGL/audio/font spoofing, a detector flagging the browser), open it at [feder-cr/firefox-stealth](https://github.com/feder-cr/firefox-stealth/issues) instead. + - **Do not** report security vulnerabilities here — follow [SECURITY.md](https://github.com/feder-cr/invisible_playwright/blob/main/SECURITY.md). + - type: input + id: version + attributes: + label: invisible_playwright version + description: Output of `invisible_playwright version` + placeholder: "0.1.0 (binary 150.0.1)" + validations: + required: true + - type: dropdown + id: os + attributes: + label: Operating system + options: + - Windows x86_64 + - Linux x86_64 + - Other (please specify in description) + validations: + required: true + - type: input + id: python + attributes: + label: Python version + placeholder: "3.11.7" + validations: + required: true + - type: textarea + id: repro + attributes: + label: Minimal reproduction + description: A small, self-contained code snippet that triggers the bug. Strip out anything unrelated. + render: python + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: Include the full error message and traceback if any. + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs / additional context + description: Browser console output, environment variables, proxy config (redact credentials), etc. + render: text + validations: + required: false + - type: checkboxes + id: confirm + attributes: + label: Confirmations + options: + - label: I have searched existing issues and this bug has not been reported. + required: true + - label: I am on the latest release. + required: true + - label: I have removed any credentials, proxy passwords, or sensitive data from logs. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6d3dace --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/feder-cr/invisible_playwright/security/advisories/new + about: Report a security issue privately. Do NOT open a public issue. + - name: Bug in the patched Firefox itself (canvas / WebGL / fonts / WebRTC / etc.) + url: https://github.com/feder-cr/firefox-stealth/issues + about: Spoofing/fingerprint bugs belong in the firefox-stealth repo. + - name: Question or general discussion + url: https://github.com/feder-cr/invisible_playwright/discussions + about: For usage questions, ideas, and chat. Bugs and features still go in issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..6693ab7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,47 @@ +name: Feature request +description: Suggest a new feature or improvement +title: "[feature] " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for the suggestion! Please check that: + - Your idea is **in scope** for this repo (the Python wrapper, sampler, CLI, packaging). + - Changes to the patched Firefox C++ source belong at [feder-cr/firefox-stealth](https://github.com/feder-cr/firefox-stealth) instead. + - You have searched [existing issues](https://github.com/feder-cr/invisible_playwright/issues?q=is%3Aissue) for similar requests. + - type: textarea + id: problem + attributes: + label: Problem + description: What problem does this solve? What can't you currently do, or what is awkward today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: How would the feature work? API sketches, CLI examples, or pseudocode welcome. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about and why they fall short. + validations: + required: false + - type: textarea + id: context + attributes: + label: Additional context + description: Links to related issues, prior art in other libraries, screenshots, etc. + validations: + required: false + - type: checkboxes + id: contribute + attributes: + label: Are you willing to contribute? + options: + - label: I'd be willing to open a PR for this if accepted. + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ebd10ec --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,40 @@ + + +## Summary + + + +## Type of change + + + +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (fix or feature that changes existing behavior) +- [ ] Documentation only +- [ ] Tests / CI / tooling + +## Related issues + + + +## How was this tested? + + + +## Checklist + +- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md). +- [ ] My commits follow [Conventional Commits](https://www.conventionalcommits.org/). +- [ ] I added or updated tests covering the change. +- [ ] `pytest` passes locally. +- [ ] I updated `README.md` / `docs/` if user-visible behavior changed. +- [ ] My change is in scope for this repo (Python wrapper / sampler / CLI / packaging — not the patched Firefox C++ source). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..127c719 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,33 @@ +# Code of Conduct + +This project follows the [Contributor Covenant, v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +## Our Pledge + +We pledge to make participation in our community a harassment-free experience for everyone. + +## Standards + +Examples of behavior that contributes to a positive environment: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission + +## Enforcement + +Instances of unacceptable behavior may be reported by contacting the maintainer at **federico.elia.majo@gmail.com**. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. + +The maintainer is obligated to maintain confidentiality with regard to the reporter of an incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2e7594a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing to invisible_playwright + +Thanks for your interest in improving this project. Contributions are welcome via issues and pull requests. + +## Quick links + +- **Bug?** Open a [bug report](https://github.com/feder-cr/invisible_playwright/issues/new?template=bug_report.yml). +- **Idea?** Open a [feature request](https://github.com/feder-cr/invisible_playwright/issues/new?template=feature_request.yml). +- **Security issue?** Do **not** open a public issue — see [SECURITY.md](SECURITY.md). +- **The C++ patches** live in the companion repo [feder-cr/firefox-stealth](https://github.com/feder-cr/firefox-stealth). Bugs in fingerprint spoofing usually belong there. + +## Scope + +This repository ships the **Python wrapper** (`invisible_playwright`) around a pre-built patched Firefox. In scope: + +- The `InvisiblePlaywright` sync/async API and launcher +- The fingerprint sampler (`_fpforge`) +- Binary download/caching, CLI, proxy plumbing +- Tests, docs, examples, packaging + +Out of scope (belongs in `firefox-stealth`): + +- Changes to the Firefox C++ source +- New preferences exposed by the patched binary +- Canvas / WebGL / WebRTC / font spoofing logic + +## Development setup + +```bash +git clone https://github.com/feder-cr/invisible_playwright.git +cd invisible_playwright +python -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install -e ".[dev]" +python -m invisible_playwright fetch # download the patched Firefox binary +``` + +Requires Python 3.11+ and one of: Windows x86_64, Linux x86_64. + +## Running tests + +```bash +pytest # unit + integration (default — fast) +pytest -m e2e # end-to-end, requires the patched binary +pytest -m slow # wheel-build regression tests +``` + +Markers are defined in `pyproject.toml`. The default run excludes `slow` and `e2e`. + +## Pull requests + +1. Fork and create a topic branch (`fix/...`, `feat/...`, `docs/...`). +2. Keep PRs focused — one logical change per PR. +3. Add or update tests for any behavior change. +4. Make sure the default `pytest` run is green. +5. Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages (e.g. `fix(launcher): handle missing profile dir`). +6. Update `README.md` or `docs/` when changing user-visible behavior. +7. Open the PR against `main`, fill in the PR template, and link any related issue. + +CI must be green before merge. + +## Reporting bugs + +Before opening, please: + +- Search [existing issues](https://github.com/feder-cr/invisible_playwright/issues) — the bug may already be tracked. +- Reproduce on the **latest release** if possible. +- Confirm the issue is in the Python wrapper, not the patched Firefox itself. If a fingerprint is leaking or a detector flags the browser, open the issue at `feder-cr/firefox-stealth` instead. + +Include: + +- OS and version, Python version, `invisible_playwright` version (`invisible_playwright version`) +- A minimal reproduction +- Expected vs actual behavior +- Relevant logs / stack traces + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License (see [LICENSE](LICENSE)). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..270fccb --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,54 @@ +# Security Policy + +## Supported versions + +Only the latest release on `main` receives security fixes. + +| Version | Supported | +|---------|-----------| +| latest | ✅ | +| older | ❌ | + +## Reporting a vulnerability + +**Please do not report security issues via public GitHub issues, discussions, or pull requests.** + +Use one of the following private channels: + +1. **GitHub Private Vulnerability Reporting** (preferred): open an advisory at https://github.com/feder-cr/invisible_playwright/security/advisories/new +2. **Email**: `federico.elia.majo@gmail.com` with subject prefix `[security][invisible_playwright]` + +Please include: + +- A clear description of the issue and impact +- Steps to reproduce (minimal repro preferred) +- The version of `invisible_playwright` and OS where it was observed +- Whether you have a suggested fix + +## What to expect + +- Acknowledgement of your report within **7 days** +- An initial assessment and tracking issue (private) within **14 days** +- Coordinated disclosure: a fix and public advisory are released together; reporters are credited unless they prefer to remain anonymous + +## Scope + +In scope: + +- The Python wrapper `invisible_playwright` (this repo) +- The binary download/verification flow (SHA256 pinning, fetch endpoints) +- The CLI + +Out of scope here (report to the relevant project): + +- Vulnerabilities in the patched Firefox C++ source — open a private report at [feder-cr/firefox-stealth](https://github.com/feder-cr/firefox-stealth/security/advisories/new) +- Vulnerabilities in upstream Firefox / mozilla-central — report to Mozilla per https://www.mozilla.org/security/ +- Vulnerabilities in third-party dependencies (`playwright`, `requests`, etc.) — report to those projects directly + +## Out of scope + +- Reports that the browser is detected by a specific anti-bot service — open a regular GitHub issue, this is a product-quality concern, not a security one +- Social engineering of maintainers +- Denial of service requiring physical access or local privileged access + +Thank you for helping keep the project and its users safe.