|
|
|
|
@@ -1,204 +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 algorithm.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
<!---
|
|
|
|
|
If the BHOS15 link ever goes dead: it's reference 30 of the zxcvbn
|
|
|
|
|
paper, aka https://dl.acm.org/citation.cfm?id=2699390 , in the
|
|
|
|
|
_Communications of the ACM_ aka CACM. (But the ACM has it paywalled.)
|
|
|
|
|
.
|
|
|
|
|
Hooray for USENIX and IEEE: the other papers' canonical links are
|
|
|
|
|
not paywalled. The Yahoo study is reference 5 in BHOS15.
|
|
|
|
|
-->
|
|
|
|
|
|
|
|
|
|
[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, IRC, and Zephyr 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
|
|
|
|
|
@@ -261,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
|
|
|
|
|
@@ -305,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.
|
|
|
|
|
|
Alya Abbott
Alex Vandiver