This document will outline the overall process for security fixes and releases. These guidelines must be taken into consideration whenever software and/or security engineers are working on vulnerabilities and other issues related to Rocket.Chat’s main product. For other public repositories, there is no need to have a separate and private repository.

Private Repository

When developing security fixes for Rocket.Chat, we must use the private security fork. This fork was created to ensure that security issues are not disclosed until there is a solution, and to prevent attackers from figuring out how to exploit vulnerabilities in Rocket.Chat and/or its clients.

The following diagram summarizes the process that must be carried out in the private repo:

Open

Synchronizing Repositories

First, we must ensure that the main branch in the private fork reflects the current state of the master branch in the public repository. To do so, we can clone the private fork and issue the following commands:

Fix Branch

Once the master and main are synchronized across repositories, you can start working on the fix. For that, you must create a new branch in the private fork with the following name convention: fix-<vulnerability-and/or-control-and-feature> - e.g. fix-nosql-injection-in-livechat, fix-email-html-injection, fix-ssrf-vulnerabilities, and so forth.

Then, after developing and testing the fix, you can open a pull request to merge such changes.

Pull Request

The PR should follow this name convention: fix: <changes that were made> - e.g. fix: validate name to prevent email HTML injection.

When opening a new PR, the default template adds Proposed changes (including videos or screenshots), Issue(s), Steps to test or to reproduce, and Further comments.

Whenever possible, we should always try to add a comprehensive description of the vulnerability, the changes being made, and why such changes are the best solution for the vulnerability. This PR can be used as an example of what can be added.

PRs will generally need to be reviewed by at least 1 software engineer and/or its code owners before it can get merged. Bypasses are only accepted in very urgent scenarios.

Last but not least, PRs that fix vulnerabilities must be merged into a release branch.

Release Branch

To merge PRs, you need to use a release branch with the following name convention: release-x.x.x. If you don’t see an existing release branch with a version number higher than the current version, you will need to create one for the next release. You can find out what the next version is by checking Rocket.Chat Releases.

Thus, if the next release is 6.11.0, you would create a branch called release-6.11.0. For urgent fixes, look at the current version of Rocket.Chat and increase the last decimal number by 1. For example, if the current version is 6.10.0 and you have urgent security fixes, you should create a branch called release-6.10.1.

Additionally, you will create another branch named with the version and “-main” added at the end, like release-6.11.0-main. A draft PR called “Release 6.11.0” will be opened to merge changes from release-x.xx.x into release-x.xx.x-main. This draft PR helps track the changes and makes it easier to import them into the public repository later.

For example, if you are working on version 6.11.0, you would have a draft PR that shows what changes from release-6.11.0 will be merged into release-6.11.0-main. An example of such a draft PR can be seen here.

This draft, however, doesn’t need to be merged into release-6.11.0-main and can be closed once the changes are ported into the public repository.

Public Repository

The following diagram summarizes the process that must be carried out in the private repo:

Open

Updating Rocket.Chat’s Public Repository

Start the new branch:

Pull security fixes into the repo:

This will pull all commits from branch release-6.11.0, but since we want all fixes into a single release, we need to rebase:

Change all commits to fixup except the first one that you should change to reword. The commit message should be fix: security hotfix. This is what git log should look like after the rebase, only a single commit after base origin (in this case origin/release-6.10.1):

After that we need to create a changeset to have an entry into the release notes.

The content of the changeset should be:

Add and commit as usual and then open a Pull Request to the develop branch.

Patches & Backports

Once the PR has been merged into the develop branch in the public repository, it’s time to start backporting the security fixes to all supported versions. You can see which versions are still being supported here.

This process is somewhat simple. On the merged PR, first add a comment with the /patch command. Dionisio, our bot, will automatically create new branches and a new PR with the same changes and point it to the right branch. After that, for the other versions, you can add /backport <version> - e.g. /backport 6.11.3, /backport 6.10.6, and so forth.

If there are any conflicts, Dionisio will add a comment with guidelines on how to proceed.

If you want to see an example, you can check this PR.