docs: Revamp production doc on security.

- Remove duplicative content.
- Move content to topic-focused pages.

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
+more on security considerations and options, see our [guide on securing
-section](../production/security-model.md) and the [Zulip help
+your Zulip server][security-guide], [security overview][security-overview],
-center](https://zulip.com/help/).
+and the [Zulip help center](https://zulip.com/help/).
+
+[security-overview]: https://zulip.com/security/
+[security-guide]: ../production/security-model.md
 
 ## Components
 

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
+- Documented how each [rate
-  [rate limit](../production/security-model.md#rate-limiting)
+  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.

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

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.
+
+<!---
+  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/
+
 ## Plug-and-play SSO (Google, GitHub, GitLab)
 
 With just a few lines of configuration, your Zulip server can

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
+admins](authentication-methods.md#email-and-password). This doc explains in
-detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use.
+more detail how we set the default threshold (`PASSWORD_MIN_GUESSES`) we use.
 
 First, read the doc section there. (It's short.)
 

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
+This page offers practical information on how to secure your Zulip server. For a
-does not cover every issue; if there are details you're curious about,
+deeper understanding of the security model, take a look at Zulip's [security
-please feel free to ask questions in [#production
+overview](https://zulip.com/security/).
-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).
 
-## 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
+1. [Limit shell access to a small set of trusted individuals.](#1-limit-shell-access-to-a-small-set-of-trusted-individuals)
-  do security for a team email server -- only trusted individuals
+2. [Consider requiring authentication with single sign-on (SSO).](#2-consider-requiring-authentication-with-single-sign-on-sso)
-  within an organization should have shell access to the server.
+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
+If you believe you've identified a security issue, please report it to Zulip's
-  or Zulip database server, or with access to the `zulip` user on a
+security team at [security@zulip.com](mailto:security@zulip.com) as soon as
-  Zulip application server, has complete control over the Zulip
+possible, so that we can address it and make a responsible disclosure.
-  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.
 
-## Encryption and authentication
+## 1. Limit shell access to a small set of trusted individuals.
 
-- Traffic between clients (web, desktop and mobile) and the Zulip
+Anyone with root access to a Zulip application server or Zulip database server,
-  server is encrypted using HTTPS. By default, all Zulip services
+or with access to the `zulip` user on a Zulip application server, has _complete
-  talk to each other either via a localhost connection or using an
+control over the Zulip installation_ and all of its data (so they can read
-  encrypted SSL connection.
+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
+## 2. Consider requiring authentication with single sign-on (SSO).
-  prevent CSRF attacks.
 
-- The preferred way to log in to Zulip is using a 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
+solution like Google authentication, LDAP, or similar, but Zulip
-  also supports password authentication. See [the authentication
+also supports password authentication. See [the authentication
-  methods documentation](authentication-methods.md) for
+methods documentation](authentication-methods.md) for
-  details on Zulip's available authentication methods.
+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
+Every Zulip user has an API key, which can be used to do essentially everything
-algorithms. Argon2 is used for all new and changed passwords as of
+that users can do when they're logged in. Make sure users know to immediately
-Zulip Server 1.6.0, but legacy PBKDF2 passwords that were last changed
+[reset their API key and password](https://zulip.com/help/protect-your-account)
-before the 1.6.0 upgrade are still supported.
+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
+## 4. Become familiar with Zulip's access management model.
-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.
+Zulip's help center offers a detailed overview of Zulip's permissions management
-  Shorter passwords are rejected even if they pass the `zxcvbn` test
+system. Reading the following guides will give you a good starting point:
-  controlled by `PASSWORD_MIN_GUESSES`.
 
-- `PASSWORD_MIN_GUESSES`: The minimum acceptable strength of the
+- [Channel types and permissions](https://zulip.com/help/channel-permissions)
-  password, in terms of the estimated number of passwords an attacker
+- [User roles](https://zulip.com/help/user-roles)
-  is likely to guess before trying this one. If the user attempts to
+- [User groups](https://zulip.com/help/user-groups)
-  set a password that `zxcvbn` estimates to be guessable in less than
+- [Restrict message editing and deletion](https://zulip.com/help/restrict-message-editing-and-deletion)
-  `PASSWORD_MIN_GUESSES`, then Zulip rejects the password.
+- [Bots overview](https://zulip.com/help/bots-overview)
 
-  By default, `PASSWORD_MIN_GUESSES` is 10000. This provides
+## 5. Understand security for user-uploaded content and user-generated requests.
-  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 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
 
 - 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.

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)

templates/corporate/security.md

@@ -4,9 +4,11 @@ priority.
 
 ## Security basics
 
-- All Zulip clients (web, mobile, desktop, terminal, and integrations)
+- All Zulip clients (web, mobile, desktop, terminal, and integrations) require
-  require TLS encryption and authentication over HTTPS for all data
+  TLS encryption and authentication over HTTPS for all data transmission between
-  transmission between clients and the server, both on LAN and the Internet.
+  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