From dcbb6253f14a5bcba54ec1911fcdb5e9303b6e38 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Fri, 1 Nov 2024 10:35:00 +0100 Subject: [PATCH] docs: add explanation about each header and middleware --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/README.md b/README.md index c3ddd22..af46bf5 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,67 @@ The CSP must add `nonce` on every request and append to script and link tags. ) ``` +## Middlewares + +This package exports 2 middlewares to be used as drop-in: `csrfProtection` and `secureRequest`. + +### CSRF Protection + +In a CSRF (Cross-Site Request Forgery) attack, a malicious actor tricks a user's browser into making unwanted requests to another site where the user is authenticated. +By exploiting the fact that browsers automatically include cookies (including session cookies) with each request to a domain. +This allows the attacker to trigger a mutation in the origin server (e.g.: change of password, email, etc). + +There are different strategies to prevent this form of attack, this middleware checks the HTTP headers to ensure the domain issuing the request is the same receiving it for `POST`. + +If the request is to be blocked, the server will respond with a [`403`](https://http.cat/403) status. + +```ts +export const csrfProtection: RequestMiddleware = (event) => { + if (csrfBlocker(event) === "block") { + // eslint-disable-next-line n/no-unsupported-features/node-builtins + event.nativeEvent.respondWith(new Response(null, { status: 403 })); + return; + } +}; +``` + +### Security Headers + +This middleware will append multiple HTTP Headers to **every request** hitting the server. + +| Header Name | Description | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Strict-Transport-Security | Enforces secure (HTTPS) connections to the server. | +| X-Frame-Options | Prevents [clickjacking](https://owasp.org/www-community/attacks/Clickjacking) by controlling whether a browser can display a page in a frame or iframe. | +| X-Content-Type-Options | Prevents `MIME` type sniffing by instructing browsers to follow the declared content type. | +| Referrer-Policy | Controls how much referrer information is included with requests. | +| Permissions-Policy | Manages permissions for APIs and features in the browser. | +| X-XSS-Protection | Fitlers cross-site scripting (XSS) in the browser. | +| Cross-Origin-Opener-Policy | Isolates browsing contexts to prevent cross-origin attacks. | +| Cross-Origin-Resource-Policy | Restricts which origins can load resources. | +| Access-Control-Allow-Origin | Specifies which origins can access the resources via cross-origin requests. | +| Content-Security-Policy\* | Defines policies to prevent a wide range of attacks, including XSS and data injection. | +| Content-Security-Policy-Report-Only\* | Same as Content-Security-Policy, but does not block, only reports to a passed URI. | + + +* CSP headers have different defaults if in production or development and these are documented below. + + +The default values for each header can be found in [defaults.ts](https://github.com/atilafassina/shieldwall/blob/main/src/lib/defaults.ts#L39-L47) file. They are strict by default and can be relaxed via configuration + +> [!TIP] +> For an extra layer of security, once the Strict-Transport-Security (HSTS) is set, you can register your domain on the [HSTS Preload List](https://hstspreload.org/). + +## Content-Security-Policy + +Given the complex nature of [Content-Security-Policy (CSP)](https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html) header, there is a lot of nuance on how to properly configure it and no _one-size-fits-all_ solution. + +For Shieldwall we have opted for the most strict options as default and it's possible to relax them through configuration as needed. +Please note that for Hot-Module Replacement to work it's required that we relax them during development to allow for inline-styles and inline-scripts. +So there are different settings for **development** and **production**. + +Additionally, CSP allows for [`nonce`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) hashes to fully secure your application against [XSS](https://owasp.org/www-community/attacks/xss/), it will work out-of-the-box for the header and you must add it on your scripts and stylesheets as [shown on usage](#usage). + ## Contributors