discourse/docs/SECURITY.md

## Discourse Security

We take security very seriously at Discourse. We welcome any peer review of our 100% open source code to ensure nobody's Discourse forum is ever compromised or hacked.

### Where should I report security issues?

In order to give the community time to respond and upgrade we strongly urge you report all security issues privately. Please use our [vulnerability disclosure program at Hacker One](https://hackerone.com/discourse) to provide details and repro steps and we will respond ASAP. If you prefer not to use Hacker One, email us directly at `team@discourse.org` with details and repro steps. Security issues *always* take precedence over bug fixes and feature work. We can and do mark releases as "urgent" if they contain serious security fixes.

For a list of recent security commits, check [our GitHub commits prefixed with SECURITY](https://github.com/discourse/discourse/search?o=desc&q=SECURITY&s=committer-date&type=Commits).

### Password Storage

Discourse uses the PBKDF2 algorithm to encrypt salted passwords. This algorithm is blessed by NIST. Security experts on the web [tend to agree that PBKDF2 is a secure choice](https://security.stackexchange.com/questions/4781/do-any-security-experts-recommend-bcrypt-for-password-storage).

**options you can customise in your production.rb file**

- `pbkdf2_algorithm`: the hashing algorithm used (default "sha256")
- `pbkdf2_iterations`: the number of iterations to run (default 64000)

### XSS

The main vector for [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks is via the post composer, as we allow users to enter Markdown, HTML (a safe subset thereof), and BBCode to format posts.

There are 3 main scenarios we protect against:

1. **Markdown preview invokes an XSS.** This is possibly severe in one specific case: when a forum staff member edits a user's post, seeing the raw markup, where a malicious user may have inserted code to run JavaScript. This code would only show up in the preview, but it would run in the context of a forum staff member, which is *very* bad.

2. **Markdown displayed on the page invokes an XSS.** To protect against client side preview XSS, Discourse uses [xss.js](https://jsxss.com/en/index.html) in the preview window.

3. **CSP is on by default** for [all Discourse installations](https://meta.discourse.org/t/mitigate-xss-attacks-with-content-security-policy/104243) as of Discourse 2.2. It can be switched off in the site settings, but it is default on.

On the server side we run a allowlist based sanitizer, implemented using the [Sanitize gem](https://github.com/rgrove/sanitize). See the [relevant Discourse code](https://github.com/discourse/discourse/blob/master/lib/pretty_text.rb).

In addition, titles and all other places where non-admins can enter code are protected either using the Handlebars library or standard Rails XSS protection.

### CSRF

[CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) allows malicious sites to perform HTTP requests in the context of a forum user without their knowledge -- mostly by getting users who already hold a valid forum login cookie to click a specific link in their web browser.

Discourse extends the built-in Rails CSRF protection in the following ways:

1. By default any non GET requests ALWAYS require a valid CSRF token. If a CSRF token is missing Discourse will raise an exception.

2. API calls using the secret API bypass CSRF checks.

3. Certain pages are "cachable", we do not render the CSRF token (`<meta name='csrf-token' ...`) on any cachable pages. Instead when users are about to perform the first non GET request they retrieve the token just in time via `GET session/csrf`

### DDOS

If you install via our recommended Docker image in our [install guide][ig], nginx is the front end web server. For additional DDOS protection we recommend placing [HAProxy](https://www.haproxy.org/) in front.

### Deployment concerns

We strongly recommend that the various Discourse processes (web server, sidekiq) run under a non-elevated account. This is handled automatically if you install via our recommended Docker image -- see [our install guide][ig] for details.

[ig]: https://github.com/discourse/discourse/blob/master/docs/INSTALL.md
move security reporting up to the top 2013-07-31 04:59:30 +08:00			`## Discourse Security`
cross-links and copyedits 2013-07-31 04:57:15 +08:00
Replace Clockwork with Sidetiq 2013-08-08 01:25:05 +08:00			`We take security very seriously at Discourse. We welcome any peer review of our 100% open source code to ensure nobody's Discourse forum is ever compromised or hacked.`
cross-links and copyedits 2013-07-31 04:57:15 +08:00
copyedits 2013-07-31 05:00:37 +08:00			`### Where should I report security issues?`

add Hacker One page to security.md 2017-01-07 15:51:12 +08:00			In order to give the community time to respond and upgrade we strongly urge you report all security issues privately. Please use our [vulnerability disclosure program at Hacker One](https://hackerone.com/discourse) to provide details and repro steps and we will respond ASAP. If you prefer not to use Hacker One, email us directly at `team@discourse.org` with details and repro steps. Security issues always take precedence over bug fixes and feature work. We can and do mark releases as "urgent" if they contain serious security fixes.
initial draft of security document 2013-07-29 14:25:28 +08:00
make security commits search order by date 2019-07-25 15:08:03 +08:00			`For a list of recent security commits, check [our GitHub commits prefixed with SECURITY](https://github.com/discourse/discourse/search?o=desc&q=SECURITY&s=committer-date&type=Commits).`
add recent security commits info 2018-09-12 03:43:52 +08:00
move security reporting up to the top 2013-07-31 04:59:30 +08:00			`### Password Storage`
initial draft of security document 2013-07-29 14:25:28 +08:00
HTTPSify links (#7046) 2019-02-22 23:29:27 +08:00			`Discourse uses the PBKDF2 algorithm to encrypt salted passwords. This algorithm is blessed by NIST. Security experts on the web [tend to agree that PBKDF2 is a secure choice](https://security.stackexchange.com/questions/4781/do-any-security-experts-recommend-bcrypt-for-password-storage).`
initial draft of security document 2013-07-29 14:25:28 +08:00
			`options you can customise in your production.rb file`

Replace Clockwork with Sidetiq 2013-08-08 01:25:05 +08:00			- `pbkdf2_algorithm`: the hashing algorithm used (default "sha256")
cross-links and copyedits 2013-07-31 04:57:15 +08:00			- `pbkdf2_iterations`: the number of iterations to run (default 64000)
initial draft of security document 2013-07-29 14:25:28 +08:00
			`### XSS`

more security doc copyedits 2013-07-31 05:08:15 +08:00			`The main vector for [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks is via the post composer, as we allow users to enter Markdown, HTML (a safe subset thereof), and BBCode to format posts.`
initial draft of security document 2013-07-29 14:25:28 +08:00
Update SECURITY.md 2018-12-20 08:55:54 +08:00			`There are 3 main scenarios we protect against:`
initial draft of security document 2013-07-29 14:25:28 +08:00
more security doc copyedits 2013-07-31 05:08:15 +08:00			`1. Markdown preview invokes an XSS. This is possibly severe in one specific case: when a forum staff member edits a user's post, seeing the raw markup, where a malicious user may have inserted code to run JavaScript. This code would only show up in the preview, but it would run in the context of a forum staff member, which is very bad.`
initial draft of security document 2013-07-29 14:25:28 +08:00
DOCS: we use xss.js and not Google Caja (#12866) The text is out of date as we migrated to xss.js quite some time ago. 2021-04-28 17:32:55 +08:00			`2. Markdown displayed on the page invokes an XSS. To protect against client side preview XSS, Discourse uses [xss.js](https://jsxss.com/en/index.html) in the preview window.`
initial draft of security document 2013-07-29 14:25:28 +08:00
Update SECURITY.md 2018-12-20 08:55:54 +08:00			`3. CSP is on by default for [all Discourse installations](https://meta.discourse.org/t/mitigate-xss-attacks-with-content-security-policy/104243) as of Discourse 2.2. It can be switched off in the site settings, but it is default on.`
add CSP info for Discourse 2.2 2018-12-20 08:54:45 +08:00
FIX: use allowlist and blocklist terminology (#10209) This is a PR of the renaming whitelist to allowlist and blacklist to the blocklist. 2020-07-27 08:23:54 +08:00			`On the server side we run a allowlist based sanitizer, implemented using the [Sanitize gem](https://github.com/rgrove/sanitize). See the [relevant Discourse code](https://github.com/discourse/discourse/blob/master/lib/pretty_text.rb).`
initial draft of security document 2013-07-29 14:25:28 +08:00
cross-links and copyedits 2013-07-31 04:57:15 +08:00			`In addition, titles and all other places where non-admins can enter code are protected either using the Handlebars library or standard Rails XSS protection.`
initial draft of security document 2013-07-29 14:25:28 +08:00
			`### CSRF`

HTTPSify links (#7046) 2019-02-22 23:29:27 +08:00			`[CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) allows malicious sites to perform HTTP requests in the context of a forum user without their knowledge -- mostly by getting users who already hold a valid forum login cookie to click a specific link in their web browser.`
initial draft of security document 2013-07-29 14:25:28 +08:00
move security reporting up to the top 2013-07-31 04:59:30 +08:00			`Discourse extends the built-in Rails CSRF protection in the following ways:`
initial draft of security document 2013-07-29 14:25:28 +08:00
			`1. By default any non GET requests ALWAYS require a valid CSRF token. If a CSRF token is missing Discourse will raise an exception.`

move security reporting up to the top 2013-07-31 04:59:30 +08:00			`2. API calls using the secret API bypass CSRF checks.`
initial draft of security document 2013-07-29 14:25:28 +08:00
move security reporting up to the top 2013-07-31 04:59:30 +08:00			3. Certain pages are "cachable", we do not render the CSRF token (`<meta name='csrf-token' ...`) on any cachable pages. Instead when users are about to perform the first non GET request they retrieve the token just in time via `GET session/csrf`
initial draft of security document 2013-07-29 14:25:28 +08:00
add ddos section, install guide references 2014-05-10 07:36:39 +08:00			`### DDOS`

HTTPSify links (#7046) 2019-02-22 23:29:27 +08:00			`If you install via our recommended Docker image in our [install guide][ig], nginx is the front end web server. For additional DDOS protection we recommend placing [HAProxy](https://www.haproxy.org/) in front.`
add ddos section, install guide references 2014-05-10 07:36:39 +08:00
cross-links and copyedits 2013-07-31 04:57:15 +08:00			`### Deployment concerns`
initial draft of security document 2013-07-29 14:25:28 +08:00
add ddos section, install guide references 2014-05-10 07:36:39 +08:00			`We strongly recommend that the various Discourse processes (web server, sidekiq) run under a non-elevated account. This is handled automatically if you install via our recommended Docker image -- see [our install guide][ig] for details.`

			`[ig]: https://github.com/discourse/discourse/blob/master/docs/INSTALL.md`