feat(appsec): Add quickstart for WordPress

crowdsec-docs/docs/appsec/intro.md

@@ -66,6 +66,7 @@ You can follow our quick start guides depending on your web server:
 
 -   [Nginx/OpenResty](/appsec/quickstart/nginxopenresty.mdx)
 -   [Traefik](/appsec/quickstart/traefik.mdx)
+-   [WordPress](/appsec/quickstart/wordpress.mdx)
 -   [CrowdSec WAF with Nginx Reverse Proxy](/u/user_guides/waf_rp_howto)
 
 Or consider learning more about the AppSec capabilities:

crowdsec-docs/docs/appsec/quickstart/wordpress.mdx

@@ -0,0 +1,318 @@
+---
+id: wordpress
+title: WordPress
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import UnderlineTooltip from '@site/src/components/underline-tooltip';
+
+# CrowdSec WAF QuickStart for WordPress
+
+## Objectives
+
+The goal of this quickstart is to set up the [AppSec Component](/appsec/intro.md#introduction) to safeguard web applications running on [WordPress](https://wordpress.org) sites.
+
+We'll deploy a [set of rules](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching) designed to block [well-known attacks](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-generic-rules) and [currently exploited vulnerabilities](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching).
+
+Additionally, we'll show how to monitor these alerts through the [console](https://app.crowdsec.net/).
+
+## Pre-requisites
+
+1. If you're new to the [AppSec Component](/appsec/intro.md#introduction) or **W**eb **A**pplication **F**irewalls, start with the [Introduction](/appsec/intro.md#introduction) for a better understanding.
+
+2. It's assumed that you have already installed:
+   - **CrowdSec [Security Engine](intro.mdx)**: for installation, refer to the [QuickStart guide](/u/getting_started/installation/linux). The AppSec Component, which analyzes HTTP requests, is included within the security engine as a [Acquisition](/log_processor/data_sources/appsec.md).
+   - **WordPress [Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [WordPress bouncer guide](/u/bouncers/wordpress). The CrowdSec WordPress plugin enables you to protect your WordPress site against malicious traffic using CrowdSec's advanced threat detection and blocklist capabilities.
+
+    This component intercepts HTTP requests at the WordPress level and forwards them to the AppSec Component for analysis and action.
+
+
+## AppSec Component Setup
+
+### Collection installation
+
+To begin setting up the AppSec Component, the initial step is to install a relevant set of rules.
+
+We will utilize the [`crowdsecurity/appsec-virtual-patching`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching) collection, which offers a wide range of rules aimed at identifying and preventing the exploitation of known vulnerabilities.
+
+This <UnderlineTooltip tooltip="Collections are bundle of parsers, scenarios, postoverflows that form a coherent package.">collection</UnderlineTooltip> is regularly updated to include protection against newly discovered vulnerabilities. Upon installation, it receives automatic daily updates to ensure your protection is always current.
+Furthermore we also install the [`crowdsecurity/appsec-generic-rules`](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-generic-rules) collection. This collection contains detection scenarios for generic attack vectors. It provides some protection in cases where specific scenarios for vulnerabilities do not exist (yet).
+
+On the machine where the Security Engine is installed, just execute the following command:
+
+:::info
+You can always view the content of a [collection on the hub](https://app.crowdsec.net/hub/author/crowdsecurity/collections/appsec-virtual-patching)
+:::
+
+```bash
+sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules
+```
+
+Executing this command will install the following items:
+
+- The [*AppSec Rules*](/appsec/rules_syntax.md) contain the definition of malevolent requests to be matched and stopped
+- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration) links together a set of rules to provide a coherent set
+- The <UnderlineTooltip tooltip="YAML files that extract relevant data from logs, such as IP addresses, timestamps, or request paths.">CrowdSec Parser</UnderlineTooltip> and <UnderlineTooltip tooltip="Behavioral rules written in a domain-specific language that define what malicious activity looks like, such as multiple failed logins in a short time.">CrowdSec Scenario(s)</UnderlineTooltip> bans for a longer duration repeating offenders
+
+### Setup the Acquisition
+
+Having installed the required components, it's time to configure the CrowdSec <UnderlineTooltip tooltip="Acquisition files tell CrowdSec where to find logs and which application they belong to.">Acquisition</UnderlineTooltip> to expose the Application Security Component to our WordPress site. This configuration allows our WordPress site to send requests to the AppSec Component for evaluation and decision-making.
+
+Steps:
+    1. Create the `/etc/crowdsec/acquis.d/` directory (if it doesn't exist on your machine)
+    ```bash
+    mkdir -p /etc/crowdsec/acquis.d/
+    ```
+    2. Create a file `/etc/crowdsec/acquis.d/appsec.yaml` with the following content:
+    ```yaml title="/etc/crowdsec/acquis.d/appsec.yaml"
+    appsec_config: crowdsecurity/appsec-default
+    labels:
+      type: appsec
+    listen_addr: 127.0.0.1:7422
+    source: appsec
+    ```
+
+The two important directives in this configuration file are:
+
+ - `appsec_config` is the name of the [*AppSec Configuration*](appsec/configuration.md#appsec-configuration) that was included in the <UnderlineTooltip tooltip="Collections are bundle of parsers, scenarios, postoverflows that form a coherent package.">Collection</UnderlineTooltip> we just installed.
+ - the `listen_addr` is the IP and port the AppSec Component will listen to.
+
+:::warning
+We do not recommend exposing the AppSec Component to the internet. It should only be accessible from the web server or WordPress application.
+::: 
+
+:::info
+You can find more about the [supported options for the acquisition here](/log_processor/data_sources/appsec.md)
+:::
+
+You can now restart CrowdSec:
+
+```bash
+sudo systemctl restart crowdsec
+```
+
+#### Testing the AppSec Component
+
+##### Verify the AppSec Component is listening
+
+To verify that the AppSec Component is running correctly, we can first check that the port `7422` is open and listening:
+
+:::note
+If you have changed the port in the configuration file, replace `7422` with the new port number.
+:::
+
+<Tabs
+  defaultValue="netstat"
+  groupId="listening-ports"
+  values={[
+    {label: 'Netstat', value: 'netstat'},
+    {label: 'SS', value: 'ss'},
+  ]}>
+
+  <TabItem value="netstat">
+    <CodeBlock className="language-bash">sudo netstat -tlpn | grep 7422</CodeBlock>
+  </TabItem>
+
+  <TabItem value="ss">
+    <CodeBlock className="language-bash">sudo ss -tlpn | grep 7422</CodeBlock>
+  </TabItem>
+</Tabs>
+
+<details>
+
+<summary>Output example</summary>
+
+```bash
+tcp        0      0 127.0.0.1:7422            0.0.0.0:*               LISTEN      12345/crowdsec
+```
+
+:::note
+The output may look differently depending on which command you used but as long as you see the port and the process `crowdsec`, it means the AppSec Component is running.
+:::
+
+</details>
+
+##### (Optional) Manually testing the AppSec Component with `curl`
+
+<details>
+  <summary>Expand for short guide</summary>
+
+Before we proceed with configuring the Remediation Component, let's verify that all our current setups are functioning correctly.
+
+1. Create a Remediation Component (Bouncer) API Key:
+
+```bash
+sudo cscli bouncers add test_waf -k this_is_a_bad_password
+API key for 'test_waf':
+
+   this_is_a_bad_password
+
+Please keep this key since you will not be able to retrieve it!
+```
+
+2. Emit a legitimate request to the AppSec Component:
+
+```bash
+curl -X POST localhost:7422/ -i -H 'x-crowdsec-appsec-uri: /test' -H 'x-crowdsec-appsec-ip: 192.168.1.1' -H 'x-crowdsec-appsec-host: foobar.com' -H 'x-crowdsec-appsec-verb: POST' -H 'x-crowdsec-appsec-api-key: this_is_a_bad_password'
+```
+
+Which will give us an answer such as:
+
+```bash
+HTTP/1.1 200 OK
+Date: Tue, 30 Jan 2024 15:43:50 GMT
+Content-Length: 36
+Content-Type: text/plain; charset=utf-8
+
+{"action":"allow","http_status":200}
+```
+
+3. Emit a malevolent request to the Appsec Component:
+
+:::info
+We're trying to access a `.env` file, a [common way to get access to some credentials forgotten by a developer.](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
+:::
+
+```bash
+curl -X POST localhost:7422/ -i -H 'x-crowdsec-appsec-uri: /.env' -H 'x-crowdsec-appsec-ip: 192.168.1.1' -H 'x-crowdsec-appsec-host: foobar.com' -H 'x-crowdsec-appsec-verb: POST' -H 'x-crowdsec-appsec-api-key: this_is_a_bad_password'
+
+```
+
+Our request is detected and blocked by the AppSec Component:
+
+```bash
+HTTP/1.1 403 Forbidden
+Date: Tue, 30 Jan 2024 15:57:08 GMT
+Content-Length: 34
+Content-Type: text/plain; charset=utf-8
+
+{"action":"ban","http_status":403}
+```
+
+Let's now delete our test API Key:
+
+```bash
+sudo cscli bouncers delete test_waf
+```
+
+</details>
+
+## Remediation Component Setup
+
+Since our AppSec Component is active and listening, we can now configure the WordPress Remediation Component to forward requests to it.
+
+The WordPress bouncer includes built-in AppSec support that can be enabled through the plugin's admin interface.
+
+### Enable AppSec in WordPress Plugin
+
+1. Log in to your WordPress admin panel
+2. Navigate to the CrowdSec plugin settings (`CrowdSec` in your admin menu)
+3. Go to the `Advanced` section
+4. Find the `AppSec component` configuration section
+5. Enable AppSec and configure the connection:
+
+   - **Enable AppSec**: Check this box to enable AppSec functionality
+   - **URL**: Set to `http://127.0.0.1:7422` (or your custom AppSec Component address)
+   - **Request timeout**: Default is 400 milliseconds (adjust as needed)
+   - **Fallback to**: Choose `captcha` (recommended) for when AppSec calls fail
+   - **Maximum body size**: Default is 1024 KB
+   - **Body size exceeded action**: Choose `headers_only` (recommended)
+
+
+![appsec-config](/img/bouncer/wordpress/screenshots/config-appsec.png)
+
+:::info
+AppSec functionality is only available when using API key authentication (not TLS certificates) in the WordPress plugin.
+:::
+
+:::note
+The AppSec Component will only be consulted when the initial LAPI remediation returns a bypass decision.
+:::
+
+## Testing the AppSec Component + Remediation Component
+
+:::note
+We're assuming WordPress is running on your local machine. Please adjust your testing accordingly if this is not the case.
+:::
+
+To test the AppSec functionality, you need to make a request that will go through the WordPress loading process. Try accessing a WordPress page with a malicious payload in the URL parameters or body.
+For example, we can try to post a request with a body that contains a malicious payload, known as a [Remote Code Execution (CVE-2022-22965)](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-CVE-2022-22965) attempt.
+
+```bash
+curl -X POST https://<your-wordpress-uri>/ -d "class.module.classLoader.resources." -o /dev/null -s -w "%{http_code}"
+```
+
+
+When the AppSec Component detects such a malicious request, you'll see that the response is a 403 (Forbidden) status code, indicating that the request was blocked.
+
+If your test is not successful, please refer to the [Health check and troubleshoot guide](/u/getting_started/health_check/) for help.
+
+
+You can also look at the metrics from `cscli metrics show appsec` which will display:
+ - the number of requests processed by the AppSec Component
+ - Individual rule matches
+
+ <details>
+  <summary>Example Output</summary>
+
+
+```bash title="sudo cscli metrics show appsec"
+Appsec Metrics:
+╭─────────────────┬───────────┬─────────╮
+│  Appsec Engine  │ Processed │ Blocked │
+├─────────────────┼───────────┼─────────┤
+│ 127.0.0.1:7422/ │ 2         │ 1       │
+╰─────────────────┴───────────┴─────────╯
+
+Appsec '127.0.0.1:7422/' Rules Metrics:
+╭─────────────────────────────────────┬───────────╮
+│             Rule ID                 │ Triggered │
+├─────────────────────────────────────┼───────────┤
+│ crowdsecurity/vpatch-CVE-2022-22965 │ 1         │
+╰─────────────────────────────────────┴───────────╯
+```
+
+</details>
+
+### Explanation
+
+What happened in the test that we just did is:
+
+ 1. We made a request with malicious payload to our WordPress site
+ 2. The WordPress bouncer plugin intercepted the request as part of the WordPress loading process
+ 3. The bouncer first checked with the local CrowdSec API for any existing decisions
+ 4. Since there was no existing ban decision, the bouncer forwarded the request to the AppSec Component at `http://127.0.0.1:7422`
+ 5. Our AppSec Component analyzed the request and matched it against the appropriate AppSec rules (here `crowdsecurity/vpatch-CVE-2022-22965` rule)
+ 6. The AppSec Component returned an HTTP 403 response to the WordPress bouncer, indicating that the request must be blocked
+ 7. The WordPress bouncer then presented the visitor with the configured ban page
+
+ ## Integration with the console
+
+If you haven't yet, follow the guide about [how to enroll your Security Engine in the console](/u/getting_started/post_installation/console).
+
+Once done, all your alerts, including the ones generated by the AppSec Component, are going to appear in the console:
+
+![appsec-console](/img/appsec_console.png)
+
+## WordPress-Specific Considerations
+
+### Understanding Plugin Limitations
+
+The WordPress bouncer has some inherent limitations you should be aware of:
+
+1. **WordPress Loading Process**: The plugin only protects requests that go through the WordPress core loading process. Direct access to PHP files outside of WordPress won't be protected.
+
+2. **Static Files**: Requests for non-PHP files (like `.env`, `.sql`, or other static files) won't be processed by the plugin since they don't go through PHP.
+
+3. **Auto Prepend File Mode**: For comprehensive protection, consider enabling [auto prepend file mode](/u/bouncers/wordpress#auto-prepend-file-mode) in the plugin settings to ensure all PHP scripts are protected.
+
+
+## Next steps
+
+You are now running the AppSec Component on your WordPress site with CrowdSec Security Engine, congrats!
+
+As the next steps, you can:
+ - [Explore the hub](https://hub.crowdsec.net) to find more rules for your use case
+ - Look at the [Rules syntax](/appsec/rules_syntax.md) and [creation process](/appsec/create_rules.md) to create your own and contribute

crowdsec-docs/sidebars.ts

@@ -711,6 +711,7 @@ const sidebarsConfig: SidebarConfig = {
 			items: [
 				{ type: "doc", id: "appsec/quickstart/nginxopenresty" },
 				{ type: "doc", id: "appsec/quickstart/traefik" },
+				{ type: "doc", id: "appsec/quickstart/wordpress" },
 			],
 		},
 		{ type: "doc", id: "appsec/configuration" },