diff --git a/.env.sample b/.env.sample index 589d10e84..387623b0c 100644 --- a/.env.sample +++ b/.env.sample @@ -14,14 +14,29 @@ SECRET_KEY_BASE= # Generate with mix phx.gen.secret 32 LIVE_VIEW_SIGNING_SALT= -WIREGUARD_PUBLIC_KEY= +# Interface public key for WireGuard. +WIREGUARD_PUBLIC_KEY=dummy + +# Port used for WireGuard. Not used in Sandbox mode. WIREGUARD_PORT=51820 + +# Interface used for WireGuard. Not used in Sandbox mode. WIREGUARD_INTERFACE_NAME=wg-firezone +# Port to listen on PHOENIX_PORT=4000 -LISTEN_ADDRESS= -SSL_CERT_FILE= -SSL_KEY_FILE= -SSL_CA_CERT_FILE= + +# Address +LISTEN_ADDRESS=0.0.0.0 + +# URL for incoming links (in outgoing emails, notifications, etc) URL_HOST=localhost + +# Whether to run *actual* WireGuard and nftables commands +FZ_SANDBOX=true + +# Email of default user ADMIN_EMAIL=fireguard@localhost + +# Used to configure routes when not running in sandbox +EGRESS_INTERFACE=dummy diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..83cec3478 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Firezone Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +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 +`conduct AT firez.one`. +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. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0fcbdf465..1c0fe1004 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,57 +1,174 @@ -# Contributing Guide +# Contributing -Read this guide before opening a pull request. +Thanks for considering contributing to Firezone! Please read this guide to get +started. -## Table of Contents +# Table of Contents -1. [Prerequisites](#prerequisites) -2. [Project Setup](#project-setup) - 1. [Provision the test VMs](#provision-the-test-vms) - 2. [Start the WireGuard interface on the - server](#start-the-wireguard-interface-on-the-server) - 3. [Start the WireGuard interface on the - client](#start-the-wireguard-interface-on-the-client) -3. [Testing](#testing) - TBD +* [Overview](#overview) +* [Developer Environment Setup](#developer-environment-setup) + * [Prerequisites](#prerequisites) + * [asdf-vm](#asdf-vm) + * [Postgresql](#postgresql) + * [Pre-commit](#pre-commit) + * [The .env File](#the-env-file) + * [Bootstrapping](#bootstrapping) +* [Reporting Bugs](#reporting-bugs) +* [Opening a Pull Request](#opening-a-pull-request) + * [Running Tests](#running-tests) + * [Use Detailed Commit Messages](#use-detailed-commit-messages) + * [Ensure Static Analysis Checks Pass](#ensure-static-analysis-checks-pass) +* [Code of Conduct](#code-of-conduct) +* [Asking for Help](#asking-for-help) + + +# Overview + +We deeply appreciate any and all contributions to the project and do our best to +ensure your contribution is included. + +To maximize your chances of getting your pull request approved, please abide by +the following general guidelines: + +1. Please adhere to our [code of conduct](CODE_OF_CONDUCT.md). +2. Please test with your code and include unit tests when possible. +3. It is up to you, the contributor, to make a case for why your change is a + good idea. +4. For any security issues, please **do not** open a Github Issue. Please + follow responsible disclosure practices laid out in + [SECURITY.md](SECURITY.md) + +# Developer Environment Setup + +We recommended macOS or Linux for developing for Firezone. You can (probably) +use Windows too with something like Windows subsystem for Linux, but we haven't +tried. ## Prerequisites -You'll need the following software installed to develop for Firezone: +### asdf-vm +While not required, we use [asdf-vm](https://asdf-vm.com) to manage language +versions for Firezone. You'll need to install the language runtimes according +to the versions laid out in the [.tool-versions](.tool-versions) file. -- [asdf](asdf-vm.com) -- A recent version of [PostgreSQL](postgresql.org) server installed and running -- [dotenv](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/dotenv) - functionality for your shell -- +If using asdf, simply run `asdf install` from the project root. -## Project Setup +### Postgresql -1. Ensure Postgres is running - ``` - $ psql -h localhost -d postgres +Firezone development requires access to a Postgresql instance. Versions 9.6 or +higher should work fine. Access can be configured using the [ +.env](#the-env-file) described below. - > CREATE ROLE firezone; - > ALTER ROLE firezone WITH LOGIN; - ``` -2. Install the language versions defined in `.tool-versions`: - ``` - # Run this from the project root - $ asdf install - ``` -3. Resolve dependencies - ``` - $ mix deps.get - $ npm install --prefix apps/fz_http/assets - ``` -4. Bootstrap DB - ``` - $ mix ecto.setup - ``` -5. Launch Server - ``` - mix phx.server - ``` +### Pre-commit -## Testing +We use [pre-commit](https://pre-commit.com) to catch any static analysis issues +before code is commit. Install with Homebrew: `brew install pre-commit` or pip: +`pip install pre-commit`. -Run tests with `mix test` from the project root. +## The .env File + +Local Firezone config is handled mostly through environment variables. Copy +copy the `.env.sample` to `.env` and edit as necessary. + +Then you'll need to load these variable into +your shell environment before running any Firezone commands. We use the +[dotenv](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/dotenv) plugin +for [oh-my-zsh](https://ohmyz.sh) but you may load these however best you see +fit. + + +## Bootstrapping + +Assuming you've completed the steps above, you should be able to get everything +set up like this: + +```bash +git clone https://github.com/firezone/firezone +cd firezone +asdf install +mix local.hex --force +mix local.rebar --force +mix deps.get +MIX_ENV=test mix do ecto.setup +mix test +``` + +This will initialize everything and run the test suite. If you have no +failures, Firezone should be properly set up 🥳. + +Then, to initialize assets, create seed data, and start the dev server: +To create seed data and start the development server: + +```bash +cd apps/fz_http +mix ecto.reset +npm install --prefix assets +cd ../.. +mix start +``` + +At this point you should be able to log into +[http://localhost:4000](http://localhost:4000) with email `factory@factory` and +password `factory`. + +# Reporting Bugs +We appreciate any and all bug reports. + +To report a bug, please first [search for it in our issues +tracker](https://github.com/firezone/firezone/issues). Be sure to search closed +issues as well. + +If it's not there, please open a new issue and include the following: + +* Description of the problem +* Expected behavior +* Steps to reproduce +* Estimated impact: High/Medium/Low +* Firezone version +* Platform architecture (amd64, aarch64, etc) +* Linux distribution +* Linux kernel version + +# Opening a Pull Request +We love pull requests! To ensure your pull request gets reviewed and merged +swiftly, please read the below *before* opening a pull request. + +## Run Tests +Please test your code. As a contributor, it is **your** responsibility to ensure +your code is bug-free, otherwise it may be rejected. It's also a good idea to +check the code coverage report to ensure your tests are covering your new +code. E.g. + +### Unit Tests +Unit tests can be run with `mix test` from the project root. + +To view line coverage information, you may run `mix coveralls.html` +which will generate an HTML coverage report in `cover/`. + +### End-to-end Tests +More comprehensive e2e testing is performed in the CI pipeline, but for security +reasons these will not be triggered automatically by your pull request and must +be manually triggered by a reviewer. + +## Use Detailed Commit Messages +This will help tremendously during our release engineering process. E.g. +```bash +read -r -d '' COMMIT_MSG << EOM +Updating the foobar widget to support additional widths + +Additional widths are needed to various device screen sizes. +Closes #72 +EOM + +git commit -m "$COMMIT_MSG" +``` + +## Ensure Static Analysis Checks Pass +This should run automatically when you run `git commit`, but in case it doesn't: +```bash +pre-commit run --all-files +``` + +# Asking For Help +If you get stuck, don't hesitate to ask for help on our mailing list at +https://discourse.firez.one. diff --git a/SECURITY.md b/SECURITY.md index 0572e2ef1..76e7ab410 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,21 @@ # Security Policy +We appreciate your help in making Firezone secure! We take security issues very +seriously and strive to fix all security issues as soon as they're reported. + +## Announcements + +We'll announce major security issues on our security mailing list located at: + +https://discourse.firez.one + +## Supported Versions + +We release security patches for supported versions of Firezone. We recommend +running the latest version of Firezone at all times. ## Reporting a Vulnerability -Please report any security issues to security AT firez.one +Please **do not** open a Github Issue for security issues you encounter. +Instead, please send an email to `security AT firez.one` describing the issue +and we'll respond as soon as possible.