{"id":13563165,"url":"https://github.com/mozilla-mobile/mozilla-vpn-client","last_synced_at":"2025-04-08T18:18:15.813Z","repository":{"id":36950892,"uuid":"287695634","full_name":"mozilla-mobile/mozilla-vpn-client","owner":"mozilla-mobile","description":"A fast, secure and easy to use VPN. Built by the makers of Firefox.","archived":false,"fork":false,"pushed_at":"2024-10-29T09:03:54.000Z","size":93847,"stargazers_count":462,"open_issues_count":887,"forks_count":113,"subscribers_count":33,"default_branch":"main","last_synced_at":"2024-10-29T10:56:59.268Z","etag":null,"topics":["firefox","mozilla","privacy","security","vpn","vpn-client"],"latest_commit_sha":null,"homepage":"https://vpn.mozilla.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla-mobile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-15T07:01:30.000Z","updated_at":"2024-10-29T09:03:55.000Z","dependencies_parsed_at":"2024-04-15T16:13:05.411Z","dependency_job_id":"1d2a490a-c9a9-45ab-b5a9-6a9136f5f55d","html_url":"https://github.com/mozilla-mobile/mozilla-vpn-client","commit_stats":null,"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-mobile%2Fmozilla-vpn-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-mobile%2Fmozilla-vpn-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-mobile%2Fmozilla-vpn-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla-mobile%2Fmozilla-vpn-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla-mobile","download_url":"https://codeload.github.com/mozilla-mobile/mozilla-vpn-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247898519,"owners_count":21014722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firefox","mozilla","privacy","security","vpn","vpn-client"],"created_at":"2024-08-01T13:01:15.821Z","updated_at":"2025-04-08T18:18:15.790Z","avatar_url":"https://github.com/mozilla-mobile.png","language":"C++","readme":"# Mozilla VPN\n\n\u003e_One tap to privacy\nSurf, stream, game, and get work done while maintaining your privacy online.\nWhether you’re traveling, using public WiFi, or simply looking for more online\nsecurity, we will always put your privacy first._\n\nSee: https://vpn.mozilla.org\n\n![Mozilla VPN Connected to New York](docs/screenshots/linux-screenshot-home-active.png) ![Mozilla VPN Server Selection](docs/screenshots/linux-screenshot-selection-multihop.png)\n\n## Getting Involved\n\nWe encourage you to participate in this open source project. We love Pull\nRequests, Bug Reports, ideas, (security) code reviews, or any other kind of\npositive contribution.\n\nBefore you attempt to make a contribution please read the [Community\nParticipation\nGuidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/).\n\nHere are some useful links to start:\n\n* [View open\n  issues](https://github.com/mozilla-mobile/mozilla-vpn-client/issues)\n* [View open pull\n  requests](https://github.com/mozilla-mobile/mozilla-vpn-client/pulls)\n* [File an\n   issue](https://github.com/mozilla-mobile/mozilla-vpn-client/issues/new/choose)\n* [File a security\n  issue](https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla%20VPN)\n* Join the [matrix\n  channel](https://chat.mozilla.org/#/room/#mozilla-vpn:mozilla.org)\n* [View the wiki](https://github.com/mozilla-mobile/mozilla-vpn-client/wiki)\n* [View the support\n  docs](https://support.mozilla.org/en-US/products/firefox-private-network-vpn)\n* Localization happens on\n  [Pontoon](https://pontoon.mozilla.org/projects/mozilla-vpn-client/).\n\n## Building the Client\n\nMoved here -\u003e [Dev-Setup](./docs/Building/index.md)\n\n### Pre-commit formatting hook\n\nIf you want to submit a pull-request, please, install the clang format\npre-commit hook that lints code.\n\n1. The standard conda environment includes the required clang-format libraries.\nIf the conda environment is *not* being used, a clang-format library will need\nto manually installed. (For example, using Homebrew on macOS:\n`brew install clang-format`.)\n\n2. The linter will need to know where to find the `clang-format-diff.py` file, so\n`CLANG_FORMAT_DIFF` must be exported. On a standard conda installation:\n`export CLANG_FORMAT_DIFF=$(find ~/miniconda3/pkgs -name clang-format-diff.py)`\n\n3. Install the pre-commit hook: `./scripts/git-pre-commit-format install`\n\n## Testing\n\n### Unit tests\n\nWhen built for any one of the desktop platforms, this project will also generate\na suite of unit tests.\n\nThe tests are built manually specifying the `build_tests` target.\n\n```bash\ncmake --build build --target build_tests -j $(nproc)\n```\n\nOnce built, you can run them with `ctest` as follows:\n\n```\nctest --test-dir build -j $(nproc) --output-on-failure\n```\n\n### Running the functional tests\n\nTo run the tests, we must set the `MVPN_BIN` environment variable and point it to the Mozilla\nVPN binary.\n\n```\n# Linux:\nexport MVPN_BIN=$(pwd)/build/mozillavpn\n# macOS:\nexport MVPN_BIN=$(pwd)/build/src/Mozilla\\ VPN.app/Contents/MacOS/Mozilla\\ VPN\n# Others:\nexport MVPN_BIN=$(pwd)/build/src/mozillavpn\n```\n\nThe functional tests also require the testing addons to be built. This sub project can be found\nat `tests/functional/addons` and can be built as follows:\n\n```\ncmake -B build-addons/ -S tests/functional/addons\ncmake --build build-addons/\nexport MVPN_ADDONS_PATH=build-addons/\n```\n\n**Other dependencies**:\n* Install node (if needed) and then `npm install` to install the testing\n  dependencies\n* Make a .env file and place it in the root folder for the repo. It should include:\n * `ARTIFACT_DIR` - optional (directory to put screenshots from test failures)\n * Sample .env file:\n  ```\n  export PATH=$PATH:~/Qt/6.6.3/macos/bin:$PATH\n  export QT_MACOS_BIN=~/Qt/6.6.3/macos/bin\n  MVPN_API_BASE_URL=http://localhost:5000\n  ARTIFACT_DIR=tests/artifact\n  ```\n\n**To run a test**: from the root of the project: `npm run functionalTest path/to/testFile.js`. To run, say, the authentication tests: `npm run functionalTest tests/functional/testAuthenticationInApp.js`.\n\n(Functional tests are run against the production build of the application by providing the\n`--testing` flag to the command line when running the app. This option switches the client in to staging mode, and\nenables mocking for platform and backend features necessary to facilitate automated testing.\nThis flag is added automatically when setupVpn.js starts the VPN, which is done for all functional tests.)\n\n## Developer Options and staging environment\n\nTo enable the staging environment, open the `Help` window, and click on the\n`Help` title text 6 times within 10 seconds to unlock the Developer Options menu.\nOn this menu, you can enable on the `Staging Server` checkbox to switch to the\nstaging environment. A full restart of the VPN will be required for this option\nto take effect.\n\n## Inspector\n\nThe inspector is a debugging tool available only when the staging environment\nis activated. When running MozillaVPN, go to the [inspector page](\nhttps://mozilla-mobile.github.io/mozilla-vpn-client/inspector/) to interact\nwith the app. Connect the inspector to the app using the web-socket interface.\nOn desktop, use `ws://localhost:8765`.\n\nThe inspector offers a number of tools to help debug and navigate through the VPN client:\n* **Shell:** By default the inspector link will take you to the Shell. From there type `help` to see the list of available commands.\n* **Logs:** Will constantly output all the app activities happening in real time. This information includes the timestamp, component and message. From the left column you can select which component(s) you'd like to monitor.\n* **Network Inspector:** Includes a list of all incoming and outgoing network requests. This is especially helpful when debugging network related issues or monitoring how the app communicates with external components such as the Guardian.\n* **QML Inspector:** Allows you to identify and inspect all QML components in the app by mirroring the local VPN client running on your machine and highlighting components by clicking on the QML instance on the right.\n\n![inspector_snapshot](https://user-images.githubusercontent.com/3746552/204422879-0799cbd8-91cd-4601-8df8-0d0e9f7cd887.png)\n\n## Glean\n\n[Glean](https://docs.telemetry.mozilla.org/concepts/glean/glean.html) is a\nMozilla analytics \u0026 telemetry solution that provides a consistent\nexperience and behavior across all of Mozilla products.\n\nWhen the client is in staging mode, pings will have the [app channel](app-channel) set to\n`staging`. This allows for filtering between staging and production pings through the\n`client_info.app_channel` metric present in all pings.\n\n[app-channel]: https://mozilla.github.io/glean/book/reference/general/initializing.html?highlight=app%20channel#gleaninitializeconfiguration\n\n### Debug tooling\n\nGlean provides a series of [debug APIs](debug-apis) to aid developers and testers\nin verifying Glean metrics.\n\nThese APIs can be accessed through the Mozilla VPN developer menu, under \"Telemetry Debugging\".\n\n#### Data review\n\nIf you are responsible for a piece of work that adds new Glean instrumentation you will need to do a data review.\nFollowing is the recommended process along with some pointers.\n\n\u003e The data review process is also described here: https://wiki.mozilla.org/Data_Collection\n\nThe basic process is this:\n\n* Implement the new instrumentation. Refer to [the Glean book](https://mozilla.github.io/glean/book/user/metrics/adding-new-metrics.html) on how to do that.\n* When adding or updating new metrics or pings, the [Glean YAML files](https://github.com/mozilla-mobile/mozilla-vpn-client/tree/main/glean) might need to be updated.\n  When that is the case a new data-review must be requested and added to the list of data-reviews for the updated/added instrumentation.\n  When updating data-review links on the YAML files, these are the things to keep in mind:\n  * Include a link to the *GitHub* bug that describes the work, this must be a public link;\n  * Put \"TBD\" in the `data_reviews` entry, that needs to be updated *before* releasing the new instrumentation and ideally before merging it;\n  * Think about whether the data you are collecting is technical or interaction, sometimes it's both. In that case pick interaction which is a higher category of data. (See more details on https://wiki.mozilla.org/Data_Collection);\n* Open a **draft** PR on GitHub;\n* Fill out the data-review[^1] form and request a data-review from one of the [Mozilla Data Stewards](https://wiki.mozilla.org/Data_Collection)[^2].\n  That can be done by opening a Bugzilla ticket or more easily by attaching the questionnaire as a comment on the PR that implements the instrumentation changes.\n  For Bugzilla, there is a special Bugzilla data review request option and for GitHub it's enough to add the chosen data steward as a reviewer for the PR.\n* The data-review questionnaire will result in a data review response. The link to that response is what should be added to the `data_review` entry on the Glean YAML files.\n  It must be a public link.\n\n\u003e Note:\n\u003e - It is **ok** for a reviewer to review and approve your code while you're waiting for data review.\n\u003e - It is **not** ok to release code that contains instrumentation changes without a data review r+. It is good practice not to merge code that does not have a data review r+.\n\n[^1]: The data-review questionnaire can be found at https://github.com/mozilla/data-review/blob/main/request.md. That can be copy pasted and filled out manually. However,\nsince the VPN application uses Glean for data collection developers can also use the [`glean_parser data-review`](https://mozilla.github.io/glean_parser/) command,\nwhich generates a mostly filled out data-review questionnaire for Glean users. The questionnaire can seem quite intimidating, but don't panic.\nFirst, look at an old data-review such as https://github.com/mozilla-mobile/mozilla-vpn-client/pull/4594.\nQuestions 1, 2, 3 an 10 are the ones that require most of your attention and thought.\nIf you don't know the answers to these questions, reach out to Sarah Bird or the product manager so you can answer these with full confidence.\n[^2]: Feel free to ping any of the data-stewards. If the collection is time sensitive consider pinging all data-stewards directly on the [data-stewards](https://matrix.to/#/#data-stewards:mozilla.org) matrix channel.\n\n## Status\n\n[![Unit Tests](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/test_unit.yaml/badge.svg)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/test_unit.yaml)\n[![Lottie Tests](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/test_lottie.yaml/badge.svg)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/test_lottie.yaml)\n[![Linters (clang, l10n, colors)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/linters.yaml/badge.svg)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/linters.yaml)\n[![Linux Packages](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/linux.yaml/badge.svg)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/linux.yaml)\n[![WebAssembly](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/wasm.yaml/badge.svg)](https://github.com/mozilla-mobile/mozilla-vpn-client/actions/workflows/wasm.yaml)\n","funding_links":[],"categories":["Applications","vpn","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++"],"sub_categories":["VPN"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-mobile%2Fmozilla-vpn-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla-mobile%2Fmozilla-vpn-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla-mobile%2Fmozilla-vpn-client/lists"}