diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index dd013b04be..0a3ffa3652 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -52,9 +52,12 @@ chamber with its own users, channels, customizations, and so on. This means that one person might be a user of multiple Zulip realms. The administrators of an organization have a great deal of control over who can register an account, what permissions new users have, etc. For -more on security considerations and options, see [the security model -section](../production/security-model.md) and the [Zulip help -center](https://zulip.com/help/). +more on security considerations and options, see our [guide on securing +your Zulip server][security-guide], [security overview][security-overview], +and the [Zulip help center](https://zulip.com/help/). + +[security-overview]: https://zulip.com/security/ +[security-guide]: ../production/security-model.md ## Components diff --git a/docs/overview/changelog.md b/docs/overview/changelog.md index 90d7a80cc1..1f7eed20fe 100644 --- a/docs/overview/changelog.md +++ b/docs/overview/changelog.md @@ -1966,8 +1966,8 @@ _Released 2023-01-23_ [Rocket.Chat imports](https://zulip.com/help/import-from-rocketchat). - Updated the Intercom integration to return success on `HEAD` requests, which it uses to verify its configuration. -- Documented how each - [rate limit](../production/security-model.md#rate-limiting) +- Documented how each [rate + limit](../production/security-model.md#6-understand-zulips-rate-limiting-system) category is used. - Documented the `reset_authentication_attempt_count` command for when users lock themselves out. diff --git a/docs/overview/release-lifecycle.md b/docs/overview/release-lifecycle.md index 010f88707c..51bf64dfa0 100644 --- a/docs/overview/release-lifecycle.md +++ b/docs/overview/release-lifecycle.md @@ -51,8 +51,10 @@ When new security releases are published, we simultaneously publish the fixes to the `main` and stable release branches, so that anyone using those branches can immediately upgrade as well. -See also our [security model][security-model] documentation. +See also our [security overview][security-overview], and our [guide on securing +your Zulip server][security-model]. +[security-overview]: https://zulip.com/security/ [security-model]: ../production/security-model.md ### Git versions diff --git a/docs/production/authentication-methods.md b/docs/production/authentication-methods.md index d7754f0949..aa5867557d 100644 --- a/docs/production/authentication-methods.md +++ b/docs/production/authentication-methods.md @@ -21,6 +21,58 @@ email and password. When first setting up your Zulip server, this method must be used for creating the initial realm and user. You can disable it after that. +### Passwords + +Zulip stores user passwords using the standard Argon2 and PBKDF2 +algorithms. Argon2 is used for all new and changed passwords as of +Zulip Server 1.6.0, but legacy PBKDF2 passwords that were last changed +before the 1.6.0 upgrade are still supported. + +When the user is choosing a password, Zulip checks the password's +strength using the popular [zxcvbn][zxcvbn] library. Weak passwords +are rejected, and strong passwords encouraged. The minimum password +strength allowed is controlled by two settings in +`/etc/zulip/settings.py`: + +- `PASSWORD_MIN_LENGTH`: The minimum acceptable length, in characters. + Shorter passwords are rejected even if they pass the `zxcvbn` test + controlled by `PASSWORD_MIN_GUESSES`. + +- `PASSWORD_MIN_GUESSES`: The minimum acceptable strength of the + password, in terms of the estimated number of passwords an attacker + is likely to guess before trying this one. If the user attempts to + set a password that `zxcvbn` estimates to be guessable in less than + `PASSWORD_MIN_GUESSES`, then Zulip rejects the password. + + By default, `PASSWORD_MIN_GUESSES` is 10000. This provides + significant protection against online attacks, while limiting the + burden imposed on users choosing a password. See + [password strength](password-strength.md) for an extended + discussion on how we chose this value. + + Estimating the guessability of a password is a complex problem and + impossible to efficiently do perfectly. For background or when + considering an alternate value for this setting, the article + ["Passwords and the Evolution of Imperfect Authentication"][bhos15] + is recommended. The [2016 zxcvbn paper][zxcvbn-paper] adds useful + information about the performance of zxcvbn, and [a large 2012 study + of Yahoo users][bon12] is informative about the strength of the + passwords users choose. + + + +[zxcvbn]: https://github.com/dropbox/zxcvbn +[bhos15]: http://www.cl.cam.ac.uk/~fms27/papers/2015-BonneauHerOorSta-passwords.pdf +[zxcvbn-paper]: https://www.usenix.org/system/files/conference/usenixsecurity16/sec16_paper_wheeler.pdf +[bon12]: http://ieeexplore.ieee.org/document/6234435/ + ## Plug-and-play SSO (Google, GitHub, GitLab) With just a few lines of configuration, your Zulip server can diff --git a/docs/production/password-strength.md b/docs/production/password-strength.md index 869f1efa19..81961a86f0 100644 --- a/docs/production/password-strength.md +++ b/docs/production/password-strength.md @@ -8,8 +8,8 @@ When a user tries to set a password, we use [zxcvbn][zxcvbn] to check that it isn't a weak one. See discussion in [our main docs for server -admins](security-model.md#passwords). This doc explains in more -detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use. +admins](authentication-methods.md#email-and-password). This doc explains in +more detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use. First, read the doc section there. (It's short.) diff --git a/docs/production/security-model.md b/docs/production/security-model.md index 9da9b653d0..1bab2ef7cc 100644 --- a/docs/production/security-model.md +++ b/docs/production/security-model.md @@ -1,207 +1,57 @@ -# Security model +# Securing your Zulip server -This section attempts to document the Zulip security model. It likely -does not cover every issue; if there are details you're curious about, -please feel free to ask questions in [#production -help](https://chat.zulip.org/#narrow/channel/31-production-help) on the -[Zulip community server](https://zulip.com/development-community/) (or if you -think you've found a security bug, please report it to -security@zulip.com so we can do a responsible security -announcement). +This page offers practical information on how to secure your Zulip server. For a +deeper understanding of the security model, take a look at Zulip's [security +overview](https://zulip.com/security/). -## Secure your Zulip server like your email server +Here are some best practices for keeping your Zulip server secure: -- It's reasonable to think about security for a Zulip server like you - do security for a team email server -- only trusted individuals - within an organization should have shell access to the server. +1. [Limit shell access to a small set of trusted individuals.](#1-limit-shell-access-to-a-small-set-of-trusted-individuals) +2. [Consider requiring authentication with single sign-on (SSO).](#2-consider-requiring-authentication-with-single-sign-on-sso) +3. [Teach users how to protect their account.](#3-teach-users-how-to-protect-their-account) +4. [Become familiar with Zulip's access management model.](#4-become-familiar-with-zulips-access-management-model)) +5. [Understand security for user-uploaded content and user-generated requests.](#5-understand-security-for-user-uploaded-content-and-user-generated-requests) +6. [Understand Zulip's rate-limiting system.](#6-understand-zulips-rate-limiting-system) - In particular, anyone with root access to a Zulip application server - or Zulip database server, or with access to the `zulip` user on a - Zulip application server, has complete control over the Zulip - installation and all of its data (so they can read messages, modify - history, etc.). It would be difficult or impossible to avoid this, - because the server needs access to the data to support features - expected of a group chat system like the ability to search the - entire message history, and thus someone with control over the - server has access to that data as well. +If you believe you've identified a security issue, please report it to Zulip's +security team at [security@zulip.com](mailto:security@zulip.com) as soon as +possible, so that we can address it and make a responsible disclosure. -## Encryption and authentication +## 1. Limit shell access to a small set of trusted individuals. -- Traffic between clients (web, desktop and mobile) and the Zulip - server is encrypted using HTTPS. By default, all Zulip services - talk to each other either via a localhost connection or using an - encrypted SSL connection. +Anyone with root access to a Zulip application server or Zulip database server, +or with access to the `zulip` user on a Zulip application server, has _complete +control over the Zulip installation_ and all of its data (so they can read +messages, modify history, etc.). This means that _only trusted individuals_ +should have shell access to your Zulip server. -- Zulip requires CSRF tokens in all interactions with the web API to - prevent CSRF attacks. +## 2. Consider requiring authentication with single sign-on (SSO). -- The preferred way to log in to Zulip is using a single sign-on (SSO) - solution like Google authentication, LDAP, or similar, but Zulip - also supports password authentication. See [the authentication - methods documentation](authentication-methods.md) for - details on Zulip's available authentication methods. +The preferred way to log in to Zulip is using a single sign-on (SSO) +solution like Google authentication, LDAP, or similar, but Zulip +also supports password authentication. See [the authentication +methods documentation](authentication-methods.md) for +details on Zulip's available authentication methods. -### Passwords +## 3. Teach users how to protect their account. -Zulip stores user passwords using the standard Argon2 and PBKDF2 -algorithms. Argon2 is used for all new and changed passwords as of -Zulip Server 1.6.0, but legacy PBKDF2 passwords that were last changed -before the 1.6.0 upgrade are still supported. +Every Zulip user has an API key, which can be used to do essentially everything +that users can do when they're logged in. Make sure users know to immediately +[reset their API key and password](https://zulip.com/help/protect-your-account) +if their credentials are compromised (e.g., their cell phone is lost or stolen). -When the user is choosing a password, Zulip checks the password's -strength using the popular [zxcvbn][zxcvbn] library. Weak passwords -are rejected, and strong passwords encouraged. The minimum password -strength allowed is controlled by two settings in -`/etc/zulip/settings.py`: +## 4. Become familiar with Zulip's access management model. -- `PASSWORD_MIN_LENGTH`: The minimum acceptable length, in characters. - Shorter passwords are rejected even if they pass the `zxcvbn` test - controlled by `PASSWORD_MIN_GUESSES`. +Zulip's help center offers a detailed overview of Zulip's permissions management +system. Reading the following guides will give you a good starting point: -- `PASSWORD_MIN_GUESSES`: The minimum acceptable strength of the - password, in terms of the estimated number of passwords an attacker - is likely to guess before trying this one. If the user attempts to - set a password that `zxcvbn` estimates to be guessable in less than - `PASSWORD_MIN_GUESSES`, then Zulip rejects the password. +- [Channel types and permissions](https://zulip.com/help/channel-permissions) +- [User roles](https://zulip.com/help/user-roles) +- [User groups](https://zulip.com/help/user-groups) +- [Restrict message editing and deletion](https://zulip.com/help/restrict-message-editing-and-deletion) +- [Bots overview](https://zulip.com/help/bots-overview) - By default, `PASSWORD_MIN_GUESSES` is 10000. This provides - significant protection against online attacks, while limiting the - burden imposed on users choosing a password. See - [password strength](password-strength.md) for an extended - discussion on how we chose this value. - - Estimating the guessability of a password is a complex problem and - impossible to efficiently do perfectly. For background or when - considering an alternate value for this setting, the article - ["Passwords and the Evolution of Imperfect Authentication"][bhos15] - is recommended. The [2016 zxcvbn paper][zxcvbn-paper] adds useful - information about the performance of zxcvbn, and [a large 2012 study - of Yahoo users][bon12] is informative about the strength of the - passwords users choose. - - - -[zxcvbn]: https://github.com/dropbox/zxcvbn -[bhos15]: http://www.cl.cam.ac.uk/~fms27/papers/2015-BonneauHerOorSta-passwords.pdf -[zxcvbn-paper]: https://www.usenix.org/system/files/conference/usenixsecurity16/sec16_paper_wheeler.pdf -[bon12]: http://ieeexplore.ieee.org/document/6234435/ - -## Messages and history - -- Zulip message content is rendered using a specialized Markdown - parser which escapes content to protect against cross-site scripting - attacks. - -- Zulip supports both public channels and private channels. - - - Any non-guest user can join any public channel in the organization, - and can view the complete message history of any public channel - without joining the channel. Guests can only access channels that - another user adds them to. - - - Organization owners and administrators can see and modify most - aspects of a private channel, including the membership and - estimated traffic. Owners and administrators generally cannot see - messages sent to private channels or do things that would - indirectly give them access to those messages, like adding members - or changing the channel privacy settings. - - - Non-admins cannot easily see which private channels exist, or interact - with them in any way until they are added. Given a channel name, they can - figure out whether a channel with that name exists, but cannot see any - other details about the channel. - - - See [channel types and permissions](https://zulip.com/help/channel-permissions) - for more details. - -- Zulip supports editing the content and topics of messages that have - already been sent. As a general philosophy, our policies provide - hard limits on the ways in which message content can be changed or - undone. In contrast, our policies around message topics favor - usefulness (e.g., for conversational organization) over faithfulness - to the original. In all configurations: - - - Message content can only ever be modified by the original author. - - - Organization administrators can configure who has permission to - delete their own message, and who can delete other users' - messages that they can see. - - - See - [Restrict message editing and deletion](https://zulip.com/help/restrict-message-editing-and-deletion) - for more details. - -## Users and bots - -- There are several types of users in a Zulip organization: organization - owners, organization administrators, members (normal users), guests, - and bots. - -- Owners and administrators have the ability to deactivate and - reactivate other human and bot users, archive channels, add/remove - administrator privileges, as well as change configuration for the - organization. - - Being an organization administrator does not generally provide the ability - to read other users' direct messages or messages sent to private - channels to which the administrator is not subscribed. There are two - exceptions: - - - Organization owners may get access to direct messages via some types of - [data export](https://zulip.com/help/export-your-organization). - - - Administrators can change the ownership of a bot. If a bot is subscribed - to a private channel, then an administrator can indirectly get access to - channel messages by taking control of the bot, though the access will be - limited to what the bot can do. (e.g., incoming webhook bots cannot read - messages.) - -- Every Zulip user has an API key, available on the settings page. - This API key can be used to do essentially everything the user can - do; for that reason, users should keep their API key safe. Users - can rotate their own API key if it is accidentally compromised. - -- To properly remove a user's access to a Zulip team, it does not - suffice to change their password or deactivate their account in a - single sign-on (SSO) system, since neither of those prevents - authenticating with the user's API key or those of bots the user has - created. Instead, you should [deactivate the user's - account](https://zulip.com/help/deactivate-or-reactivate-a-user) via - Zulip's "Organization settings" interface. - -- The Zulip mobile apps authenticate to the server by sending the - user's password and retrieving the user's API key; the apps then use - the API key to authenticate all future interactions with the site. - Thus, if a user's phone is lost, in addition to changing passwords, - you should rotate the user's Zulip API key. - -- Guest users are like Members, but they do not have automatic access - to public channels. - -- Zulip supports several kinds of bots with different capabilities. - - - Incoming webhook bots can only send messages into Zulip. - - Outgoing webhook bots and Generic bots can essentially do anything a - non-administrator user can, with a few exceptions (e.g., a bot cannot - log in to the web application, register for mobile push - notifications, or create other bots). - - Bots with the `can_forge_sender` permission can send messages that appear to have been sent by - another user. They also have the ability to see the names of all - channels, including private channels. This is important for implementing - integrations like the Jabber and IRC mirrors. - - These bots cannot be created by Zulip users, including - organization owners. They can only be created on the command - line (via `manage.py change_user_role can_forge_sender`). - -## User-uploaded content and user-generated requests +## 5. Understand security for user-uploaded content and user-generated requests. - Zulip supports user-uploaded files. Ideally they should be hosted from a separate domain from the main Zulip server to protect against @@ -264,7 +114,7 @@ strength allowed is controlled by two settings in [smokescreen-setup]: deployment.md#customizing-the-outgoing-http-proxy [proxy.enable_for_camo]: system-configuration.md#enable_for_camo -## Rate limiting +## 6. Understand Zulip's rate-limiting system. Zulip has built-in rate limiting of login attempts, all access to the API, as well as certain other types of actions that may be involved in @@ -308,13 +158,3 @@ See also our [API documentation on rate limiting][rate-limit-api]. [management-commands]: ../production/management-commands.md [rate-limit-api]: https://zulip.com/api/rest-error-handling#rate-limit-exceeded - -## Final notes and security response - -If you find some aspect of Zulip that seems inconsistent with this -security model, please report it to security@zulip.com so that we can -investigate and coordinate an appropriate security release if needed. - -Zulip security announcements will be sent to -zulip-announce@googlegroups.com, so you should subscribe if you are -running Zulip in production. diff --git a/starlight_help/src/content/docs/contact-support.mdx b/starlight_help/src/content/docs/contact-support.mdx index 0006e1bd44..3ef0cc814e 100644 --- a/starlight_help/src/content/docs/contact-support.mdx +++ b/starlight_help/src/content/docs/contact-support.mdx @@ -73,6 +73,12 @@ for your organization. [development-community-channels]: https://zulip.com/development-community/#channels-for-zulip-users-and-administrators +## Security + +If you believe you've identified a security issue, please report it to Zulip's +security team at [security@zulip.com](mailto:security@zulip.com) as soon as +possible, so that we can address it and make a responsible disclosure. + ## Related articles * [Zulip Cloud billing](/help/zulip-cloud-billing) diff --git a/templates/corporate/security.md b/templates/corporate/security.md index c88733ff58..2ba26fbc09 100644 --- a/templates/corporate/security.md +++ b/templates/corporate/security.md @@ -4,9 +4,11 @@ priority. ## Security basics -- All Zulip clients (web, mobile, desktop, terminal, and integrations) - require TLS encryption and authentication over HTTPS for all data - transmission between clients and the server, both on LAN and the Internet. +- All Zulip clients (web, mobile, desktop, terminal, and integrations) require + TLS encryption and authentication over HTTPS for all data transmission between + clients and the server, both on LAN and the Internet. By default, all Zulip + services talk to each other either via a localhost connection or using an + encrypted SSL connection. - All Zulip Cloud customer data is encrypted at rest. Self-hosted Zulip can be configured for encryption at rest via your hosting provider, or by setting up hardware and software disk encryption of the database and other data storage @@ -20,6 +22,8 @@ priority. [deployed on multiple servers](https://zulip.readthedocs.io/en/latest/production/deployment.html), all connections between parts of the Zulip infrastructure can be secured with TLS or SSH. +- Zulip requires CSRF tokens in all interactions with the web API to + prevent CSRF attacks. - Message content can be [excluded from mobile push notifications][redact-content], to avoid displaying message content on locked mobile screens, and to