+
+
+
+**Looking for other integrations?** Check out the [full list of remediation components](https://hub.crowdsec.net/browse/#remediation-components) on the CrowdSec Hub. We're constantly adding new integrations!
-## In-band Rules and Out-of-Band Rules
+## Inband Rules and Out-Of-Band Rules
The AppSec component relies on rules to inspect HTTP requests:
-- In-band rules are meant to interrupt request processing
+- Inband rules are meant to interrupt request processing
- Out-Of-Band rules are non-blocking and are evaluated asynchronously
### In-band rule processing
-The security engine first evaluates the in-band rules, designed to identify and block specific requests.
+The security engine first evaluates the inband rules, designed to identify and block specific requests.
Once these rules are evaluated, a response is relayed to the remediation component.
This leads to two possible outcomes:
@@ -45,18 +114,18 @@ This leads to two possible outcomes:
1. If an in-band rule is triggered, the remediation component returns a 403 or a captcha challenge to the requester, stopping processing.
2. Otherwise, the request will be normally processed
-### Out-of-band rules processing
+### Out-of-band rule processing
-In the background, the security engine then evaluates out-of-band rules. These rules do not impact performance or response time, as they run after the AppSec Component instructs the web server to continue or stop processing the request.
+In the background, the security engine will then evaluate the out-of-band rules. These rules do not impact performance or response time, as they are evaluated after the AppSec Component instructs the webserver to continue or stop processing the request.
They are usually meant to detect repetitive unwanted behavior (for example, application spam, resource enumeration, scalping). When these rules trigger, they emit an event that the Security Engine processes like a log line.
## Post processing
-When a request triggers one or more rules, either in the in-band section (blocking) or out-of-band (non-blocking), several things happen:
+When a request triggers one or more rules, either in the inband section (blocking) or out-of-band (non-blocking), several things happen:
-- In-band (blocking) rules appear in your `cscli alerts list` (and thus in your [console dashboard](https://app.crowdsec.net)).
-- In-band and Out-of-Band rules trigger an internal CrowdSec event that can be treated like any log line.
+- Inband (blocking) rules will appear in your `cscli alerts list` (and thus in your [console dashboard](https://app.crowdsec.net)).
+- Inband and Out-Of-Band rules will trigger an internal crowdsec event that can be treated as any log lines.
This lets scenarios leverage WAF rule events, such as extending a ban for an IP that triggers multiple virtual patching rules.
@@ -66,13 +135,14 @@ You can follow our quick start guides depending on your web server:
- [Nginx/OpenResty](quickstart/nginxopenresty)
- [Traefik](quickstart/traefik)
+- [HAProxy (SPOA)](quickstart/haproxy_spoa)
- [WordPress](quickstart/wordpress)
- [CrowdSec WAF with Nginx Reverse Proxy](/u/user_guides/waf_rp_howto)
Or consider learning more about the AppSec capabilities:
-- **Rules**: [How to read, write and debug rules](/appsec/rules_syntax.md)
-- **Scenarios**: [How to create scenarios that leverage the AppSec Component events](/appsec/alerts_and_scenarios.md)
-- **Hooks**: [To customize behavior of the AppSec at runtime](/appsec/hooks.md)
-- **Troubleshoot**: [How to troubleshoot the behavior of the AppSec Component](/appsec/troubleshooting.md)
-- **AppSec Protocol**: [If you're maintaining or creating a remediation component and want to add AppSec capabilities](/appsec/protocol.md)
+- **Rules**: [How to read, write and debug rules](rules_syntax.md)
+- **Scenarios**: [How to create scenarios that leverage the AppSec Component events](alerts_and_scenarios.md)
+- **Hooks**: [To customise behavior of the AppSec at runtime](hooks.md)
+- **Troubleshoot**: [How to troubleshoot the behavior of the AppSec Component](troubleshooting.md)
+- **AppSec Technical Details**: [For developers integrating with the AppSec Component](protocol.md)
diff --git a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/general.mdx b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/general.mdx
index 5708b2de0..ff7f2eaa6 100644
--- a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/general.mdx
+++ b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/general.mdx
@@ -24,10 +24,12 @@ This guide covers the core AppSec Component setup that applies to all web server
AppSec setup has two steps:
- Download rules and configuration collections.
-- Configure AppSec as a new acquisition datasource.
+- Configure AppSec as a new acquisition datasource ([AppSec datasource](/log_processor/data_sources/appsec.md)).
The following sections will guide you through the default setup.
+After installation, verify everything works with the [🩺 Health Check](/u/getting_started/health_check).
+
### Collection Installation
Install the essential AppSec collections that provide virtual patching rules and generic attack detection:
@@ -39,32 +41,35 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri
These collections include:
- **Virtual Patching Rules**: Protection against known vulnerabilities (CVEs)
- **Generic Attack Detection**: Common web attack patterns
-- **AppSec Configuration**: Default configuration linking rules together
+- **AppSec Configuration**: Default [AppSec configuration file](/appsec/configuration.md) linking rules together
- **CrowdSec Parsers & Scenarios**: For processing AppSec events and creating alerts
### Acquisition Configuration
-Configure CrowdSec to expose the AppSec Component by creating an acquisition file:
+Configure CrowdSec to expose the AppSec Component by creating an acquisition file ([AppSec datasource](/log_processor/data_sources/appsec.md)).
1. Create the acquisition directory (if it doesn't exist):
- ```bash
- sudo mkdir -p /etc/crowdsec/acquis.d/
- ```
+
+```bash
+sudo mkdir -p /etc/crowdsec/acquis.d/
+```
2. Create the AppSec acquisition configuration:
- ```bash
- sudo cat > /etc/crowdsec/acquis.d/appsec.yaml << EOF
- appsec_config: crowdsecurity/appsec-default
- labels:
- type: appsec
- listen_addr: 127.0.0.1:7422
- source: appsec
- name: myAppSecComponent
- EOF
- ```
+
+```bash
+sudo cat > /etc/crowdsec/acquis.d/appsec.yaml << EOF
+appsec_configs:
+ - crowdsecurity/appsec-default
+labels:
+ type: appsec
+listen_addr: 127.0.0.1:7422
+source: appsec
+name: myAppSecComponent
+EOF
+```
**Configuration explained:**
-- `appsec_config`: Uses the default configuration from the installed collections
+- `appsec_configs`: Uses the [AppSec configuration(s)](/appsec/configuration.md) from the installed collections
- `listen_addr`: IP and port where the AppSec Component listens (default: 127.0.0.1:7422)
- `source`: Identifies this as an AppSec data source
- `name`: A friendly name for your AppSec component
@@ -113,7 +118,7 @@ tcp 0 0 127.0.0.1:7422 0.0.0.0:* LISTEN
```
:::note
-The output may look different depending on the command you used. As long as you see port 7422 and the `crowdsec` process, the AppSec Component is running.
+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.
:::
@@ -135,14 +140,15 @@ INFO[...] Appsec Runner ready to process event
Now that the AppSec Component is configured and running, you need to:
1. **Configure your remediation component** to forward requests to `http://127.0.0.1:7422`
-2. **Test the setup** [by triggering a rule](/appsec/quickstart/general.mdx#testing-detection)
+2. **Test the setup** [by triggering a rule](#testing-detection)
3. **Monitor alerts** with `sudo cscli alerts list` or in the [CrowdSec Console](https://app.crowdsec.net)
For specific remediation component configuration, see:
-- [Nginx/OpenResty Setup](/appsec/quickstart/nginxopenresty.mdx)
-- [Traefik Setup](/appsec/quickstart/traefik.mdx)
-- [WordPress Setup](/appsec/quickstart/wordpress.mdx)
-- [Check the Hub for other remediation components supporting AppSec](https://app.crowdsec.net/hub/remediation-components)
+- [Nginx/OpenResty Setup](nginxopenresty.mdx)
+- [Traefik Setup](traefik.mdx)
+- [HAProxy (SPOA) Setup](haproxy_spoa.mdx)
+- [WordPress Setup](wordpress.mdx)
+- [Check the hub for other remediation components supporting AppSec](https://app.crowdsec.net/hub/remediation-components)
### Testing Detection
@@ -176,7 +182,7 @@ This scenario can only be triggered again after a 1-minute delay.
### Multiple AppSec Configurations
-You can [load multiple AppSec configurations](/appsec/vpatch_and_crs) for different rule sets:
+You can [load multiple AppSec configurations](/appsec/configuration_creation_testing.md#defining-multiple-appsec-configurations) for different rule sets:
```yaml
# /etc/crowdsec/acquis.d/appsec.yaml
diff --git a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/haproxy_spoa.mdx b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/haproxy_spoa.mdx
new file mode 100644
index 000000000..e43a8b06f
--- /dev/null
+++ b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/haproxy_spoa.mdx
@@ -0,0 +1,150 @@
+---
+id: haproxy_spoa
+title: QuickStart - HAProxy (SPOA)
+---
+
+import UnderlineTooltip from '@site/src/components/underline-tooltip';
+
+# CrowdSec WAF QuickStart for HAProxy (SPOA)
+
+## Objectives
+
+Set up the [AppSec Component](/appsec/intro.md#introduction) to protect web applications running behind [HAProxy](https://www.haproxy.org/) using the **HAProxy SPOA remediation component**.
+
+You will:
+- Enable CrowdSec AppSec (WAF) in the Security Engine.
+- Install and configure `crowdsec-haproxy-spoa-bouncer` so HAProxy can forward HTTP requests to AppSec.
+- Validate everything by triggering a test detection.
+
+## Prerequisites
+
+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).
+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).
+ - **HAProxy**: already running and proxying your application(s).
+ - **HAProxy SPOA [Remediation Component](/u/bouncers/intro)**: `crowdsec-haproxy-spoa-bouncer`.
+
+:::tip Already did the base setup?
+If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup).
+:::
+
+## AppSec Component Setup
+
+### Collection installation
+
+Install the main AppSec rule collections:
+
+```bash
+sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecurity/appsec-generic-rules
+```
+
+These
+
+Nginx
+Quick Start Guide →
+
+
+
+Nginx
+Quick Start Guide →
+
+
+OpenResty
+Quick Start Guide →
+
+
+
+OpenResty
+Quick Start Guide →
+
+
+Traefik
+Quick Start Guide →
+
+
+
+Traefik
+Quick Start Guide →
+
+
+HAProxy
+Quick Start Guide →
+
+
+
+HAProxy
+Quick Start Guide →
+
+
+WordPress
+Quick Start Guide →
+
+
+
+WordPress
+Quick Start Guide →
+
+
+
+
+:::note
+After the rollout, you can optionally check that the right container is deployed with something like:
+
+`kubectl -n ingress-nginx exec -ti CrowdSec Ingress-NGINX Remediation Configuration Explained
+ +This `values.yaml` snippet integrates the CrowdSec remediation (Lua bouncer) +into the `ingress-nginx` controller by injecting the Lua plugin, generating its +configuration, and enabling it inside NGINX. + +#### Controller Image Override +```yaml +controller: + image: + registry: docker.io + image: crowdsecurity/controller + tag: v1.13.2 + digest: sha256:... +``` + +The controller image is replaced with a CrowdSec-enabled build that includes the +required Lua integration points. + +#### Shared Volume for the Plugin + +```yaml +extraVolumes: + - name: crowdsec-bouncer-plugin + emptyDir: {} +``` + +An emptyDir volume is used to hold the Lua bouncer plugin. It will be filled by +an initContainer and mounted into the main controller. + +#### InitContainer: Plugin Fetch and Configuration + +```yaml +extraInitContainers: + - name: init-clone-crowdsec-bouncer + image: crowdsecurity/lua-bouncer-plugin:latest + env: + - name: API_URL + value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" + - name: API_KEY + value: privateKey-foo + - name: BOUNCER_CONFIG + value: "/crowdsec/crowdsec-bouncer.conf" + - name: APPSEC_URL + value: "http://crowdsec-appsec-service.crowdsec.svc.cluster.local:7422" + - name: APPSEC_FAILURE_ACTION + value: "ban" + - name: APPSEC_CONNECT_TIMEOUT + value: "100" + - name: APPSEC_SEND_TIMEOUT + value: "100" + - name: APPSEC_PROCESS_TIMEOUT + value: "1000" + - name: ALWAYS_SEND_TO_APPSEC + value: "false" + command: + - sh + - -c + - | + sh /docker_start.sh + mkdir -p /lua_plugins/crowdsec/ + cp -R /crowdsec/* /lua_plugins/crowdsec/ + volumeMounts: + - name: crowdsec-bouncer-plugin + mountPath: /lua_plugins +``` + +The initContainer generates the plugin configuration (crowdsec-bouncer.conf) +from environment variables and copies the Lua plugin files into the shared +volume so the main controller can load them. + +#### Mounting the Plugin in NGINX + +```yaml +extraVolumeMounts: + - name: crowdsec-bouncer-plugin + mountPath: /etc/nginx/lua/plugins/crowdsec + subPath: crowdsec +``` + +This mounts the plugin files inside the directory where ingress-nginx expects +Lua plugins. + +#### NGINX Configuration to Enable the Plugin + +``` +config: + plugins: "crowdsec" + lua-shared-dicts: "crowdsec_cache: 50m" + server-snippet: | + lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt" + resolver local=on ipv6=off; +``` + +This snippet enables the crowdsec Lua plugin, aAllocates shared memory for +caching LAPI/AppSec results and ensures Lua HTTPS validation and DNS resolution +work properly. + +#### Summary + +This configuration: +* Injects the CrowdSec Lua bouncer plugin into ingress-nginx. +* Generates its configuration via an initContainer. +* Mounts it into NGINX so it is executed during request processing. +* Enables both LAPI enforcement and optional AppSec forwarding depending on settings. +
+ -- 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-env-access │ 1 │
+╰─────────────────────────────────┴───────────╯
+```
+
+
+You can test and investigate further with [Stack
+Health-Check](/u/getting_started/health_check#trigger-crowdsec-test-scenarios) and [Appsec Troubleshooting
+guide](/appsec/troubleshooting.md)
+
+## 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, appear in the Console:
+
+
+
+## Next steps
+
+You are now running the AppSec Component on your CrowdSec Security Engine.
+
+As the next steps, you can:
+ - Look at [WAF Deployment Strategies](/appsec/advanced_deployments.mdx) to discover how to gradually improve your WAF security.
+ - Look at the [Rules syntax](/appsec/rules_syntax.md) and [creation process](/appsec/create_rules.md) to create your own and contribute
+ - Take a look at [the benchmarks](/appsec/benchmark.md)
diff --git a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/nginxopenresty.mdx b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/nginxopenresty.mdx
index 0deba8135..d57efa85a 100644
--- a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/nginxopenresty.mdx
+++ b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/nginxopenresty.mdx
@@ -24,7 +24,7 @@ Additionally, we'll show how to monitor these alerts through the [Console](https
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).
+ - **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).
- One of the supported web servers for this guide:
- Nginx **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/nginx).
- OpenResty **[Remediation Component](/u/bouncers/intro)**: installation instructions are available in the [QuickStart guide](/u/bouncers/openresty).
@@ -35,6 +35,10 @@ Additionally, we'll show how to monitor these alerts through the [Console](https
The reason we provide Nginx and OpenResty in a single guide is that OpenResty is a web server based on Nginx just the configuration paths are different
:::
+:::tip Already did the base setup?
+If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup).
+:::
+
## AppSec Component Setup
### Collection installation
@@ -58,31 +62,34 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri
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 Rules*](/appsec/rules_syntax.md) contain the definition of malicious requests to be matched and stopped
- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set
- The Example Output
+ +```bash title="kubectl exec -n crowdsec -ti crowdsec-appsec-
+
+
+### Explanation
+
+What happened in the test that we just did is:
+
+1. We did a request (`localhost/.env`) to our web server
+2. Thanks to the NPMplus Remediation Component configuration, the request was forwarded to `http://crowdsec:7422` (or the appropriate Docker network address)
+3. Our AppSec Component, listening on `0.0.0.0:7422` analyzed the request
+4. The request matches the [AppSec rule to detect .env access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
+5. The AppSec Component thus answered with [HTTP 403](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) to the Remediation Component, indicating that the request must be blocked
+6. The web server then presented us with the default "request blocked" 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, appear in the Console:
+
+
+
+## Next steps
+
+You are now running the AppSec Component on your CrowdSec Security Engine with NPMplus, congrats!
+
+:::info
+You can now log into the NPMplus admin interface at `https://Example Output
+ +```bash title="docker exec crowdsec cscli metrics show appsec" +Appsec Metrics: +╭─────────────────┬───────────┬─────────╮ +│ Appsec Engine │ Processed │ Blocked │ +├─────────────────┼───────────┼─────────┤ +│ 0.0.0.0:7422/ │ 2 │ 1 │ +╰─────────────────┴───────────┴─────────╯ + +Appsec '0.0.0.0:7422/' Rules Metrics: +╭─────────────────────────────────┬───────────╮ +│ Rule ID │ Triggered │ +├─────────────────────────────────┼─────────┤ +│ crowdsecurity/vpatch-env-access │ 1 │ +╰─────────────────────────────────┴───────────╯ +``` + +You can test and investigate further with [Stack Health-Check](/u/getting_started/health_check) and [Appsec Troubleshooting guide](/appsec/troubleshooting.md) + +
-
+We can't cover all the possible configurations for Traefik in this guide, so please refer to the [official documentation](https://doc.traefik.io/traefik/) for more information.
### Directives
@@ -446,11 +407,55 @@ If the AppSec Component returns `500` status code should the request be blocked.
If the AppSec Component is unreachable should the request be blocked.
-## Validate the stack
+## Testing the AppSec Component + Remediation Component
+
+:::note
+We're assuming the web server is installed on the same machine and is listening on port 80. Please adjust your testing accordingly if this is not the case.
+:::
+
+If you try to access `http://localhost/.env` from a browser, your request will be blocked, resulting in the display of the following HTML page:
+
+
+
+We can also look at the metrics from `cscli metrics show appsec` it will display:
+ - the number of requests processed by the AppSec Component
+ - Individual rule matches
+
+ The traefik configuration for testing this quickstart guide has been done with the following values.yaml
-```yaml title="values.yaml" -deployment: - kind: DaemonSet # run on each node so a sidecar crowdsec can tail Traefik logs - -service: - type: LoadBalancer # expose Traefik entrypoints through your cloud LB - annotations: - service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol: "true" # forward client IPs via DigitalOcean proxy protocol - spec: - externalTrafficPolicy: Local # keep original source IPs for CrowdSec decisions - -# Make Traefik actually write a file that can be parsed -logs: - access: - enabled: true # ensure access logs are produced - format: json # structured logs expected by the bouncer parser - fields: - defaultMode: keep - names: - ServiceName: keep # keep service name for troubleshooting - general: - level: INFO # avoid noisy debug output in production - format: json # align general logs with access log format - -# Proxy Protocol needs “enabled”, not only trustedIPs -additionalArguments: - - --accesslog=true # double-check logging stays on even if values drift - - --accesslog.format=json # enforce JSON formatting at the CLI level - - --entrypoints.web.proxyProtocol=true # enable Proxy Protocol on the HTTP entrypoint - - --entrypoints.websecure.proxyProtocol=true # enable Proxy Protocol on the HTTPS entrypoint - - --entrypoints.web.proxyProtocol.trustedIPs=10.0.0.0/8,192.168.0.0/16 # trust proxy headers from your internal ranges - - --entrypoints.websecure.proxyProtocol.trustedIPs=10.0.0.0/8,192.168.0.0/16 # same trust list for HTTPS - - --providers.kubernetesingress # watch standard Ingress resources - - --providers.kubernetescrd # watch Traefik CRD resources - -# Traefik middleware configuration -experimental: - plugins: - crowdsec-bouncer-traefik-plugin: - moduleName: "github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin" - version: "v1.4.5" # pin plugin release for deterministic behaviour -``` -
+
+
+### Explanation
+
+What happened in the test that we just did is:
-Follow the [Stack health check](/u/getting_started/health_check) to confirm the
-CrowdSec engine, AppSec Component, and Traefik bouncer are working together as
-expected.
+ 1. We did a request (`localhost/.env`) to our local webserver
+ 2. Thanks to the Remediation Component configuration, forwarded the request to `http://127.0.0.1:7422`
+ 3. Our AppSec Component, listening on `http://127.0.0.1:7422` analyzed the request
+ 4. The request matches the [AppSec rule to detect .env access](https://app.crowdsec.net/hub/author/crowdsecurity/appsec-rules/vpatch-env-access)
+ 5. The AppSec Component thus answered with [HTTP 403](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403) to the Remediation Component, indicating that the request must be blocked
+ 6. The web server then presented us with the default "request blocked" page.
## Integration with the Console
@@ -462,8 +467,9 @@ Once done, all your alerts, including the ones generated by the AppSec Component
## Next steps
-You are now running the AppSec Component on your Crowdsec Security Engine, congrats!
+You are now running the AppSec Component on your CrowdSec Security Engine.
As the next steps, you can:
+ - Look at [WAF Deployment Strategies](/appsec/advanced_deployments.mdx) to discover how to gradually improve your WAF security.
- Look at the [Rules syntax](/appsec/rules_syntax.md) and [creation process](/appsec/create_rules.md) to create your own and contribute
- - Learn more about AppSec’s advanced capabilities in [Advanced WAF Deployments](/docs/next/appsec/advanced_deployments/)
+ - Take a look at [the benchmarks](/appsec/benchmark.md)
diff --git a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/wordpress.mdx b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/wordpress.mdx
index d4a7c66cd..2c9f76874 100644
--- a/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/wordpress.mdx
+++ b/crowdsec-docs/versioned_docs/version-v1.7/appsec/quickstart/wordpress.mdx
@@ -23,11 +23,14 @@ Additionally, we'll show how to monitor these alerts through the [Console](https
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).
+ - **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.
+:::tip Already did the base setup?
+If you already completed the [General Setup](general.mdx) (collections + acquisition), skip to [Remediation Component Setup](#remediation-component-setup).
+:::
## AppSec Component Setup
@@ -52,31 +55,34 @@ sudo cscli collections install crowdsecurity/appsec-virtual-patching crowdsecuri
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 Rules*](/appsec/rules_syntax.md) contain the definition of malicious requests to be matched and stopped
- The [*AppSec Configuration*](/appsec/configuration.md#appsec-configuration-files) links together a set of rules to provide a coherent set
- The Example Output
+ +```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-env-access │ 1 │ +╰─────────────────────────────────┴───────────╯ +``` + +You can test and investigate further with [Stack +Health-Check](/u/getting_started/health_check) and [Appsec Troubleshooting +guide](/appsec/troubleshooting.md) + +
@@ -23,20 +23,20 @@ CrowdSec is a modular security tool offering [behavior-based detection](https://
-The crowd-sourced aspect allows the sharing of attacks they detected and blocked. Participants of this crowd-sourced threat intel receive, automatically via the security engine, a curated list of validated attackers (community blocklist) enhancing their real-time protection capabilities by taking preemptive actions against known threats.
+CrowdSec is crowdsourced: when you participate, you share the attacks you detect and block. In return, the Security Engine automatically downloads a curated list of validated attackers (the community blocklist), so you can take action sooner against known threats.
## Main Features
In addition to the core "detect and react" mechanism, CrowdSec is committed to several other key aspects:
-- **Easy Installation**: Effortless out-of-the-box installation on all [supported platforms](/u/getting_started/intro).
-- **Simplified Daily Operations**: You have access to our Web UI administration via [CrowdSec's console](http://app.crowdsec.net) or the powerful [Command line tool cscli](/cscli/cscli.md) for effortless maintenance and keeping your detection mechanisms up-to-date.
-- **Reproducibility**: The Security Engine can analyze not only live logs but also [cold logs](/u/user_guides/replay_mode), making it easier to detect potential false triggers, conduct forensic analysis, or generate reports.
-- **Versatile**: The Security Engine can analyze [system logs](/log_processor/data_sources/introduction.md) and [HTTP Requests](/appsec/intro.md) to exhaustively protect your perimeter.
+- **Easy Installation**: Get started quickly on all [supported platforms](/u/getting_started/intro).
+- **Simplified Daily Operations**: Manage and maintain your setup from the [CrowdSec Console](http://app.crowdsec.net) (Web UI) or with the [cscli command-line tool](/cscli/cscli.md).
+- **Reproducibility**: Analyze live logs and [cold logs](/u/user_guides/replay_mode) to validate detections, run forensic analysis, or generate reports.
+- **Versatile**: Protect your perimeter by analyzing [system logs](/log_processor/data_sources/introduction.md) and [HTTP requests](/appsec/intro.md).
- **Observability**: Providing valuable insights into the system's activity:
- - Users can view/manage alerts from the ([Console](https://app.crowdsec.net/signup)).
- - Operations personnel have access to detailed Prometheus metrics ([Prometheus](/observability/prometheus.md)).
- - Administrators can utilize a user-friendly command-line interface tool ([cscli](/observability/cscli.md)).
+ - View and manage alerts in the [Console](https://app.crowdsec.net/signup).
+ - Expose detailed [Prometheus metrics](/observability/prometheus.md).
+ - Use the [cscli CLI](/observability/cscli.md) for administration.
- **API-Centric**: All components communicate via an [HTTP API](/local_api/intro.md), facilitating multi-machine setups.
## Architecture
@@ -49,23 +49,23 @@ In addition to the core "detect and react" mechanism, CrowdSec is committed to s
Under the hood, the Security Engine has various components:
-- The [Log Processor](/log_processor/intro.mdx) is in charge of detection: it analyzes logs from [various data sources](/log_processor/data_sources/introduction.md) or [HTTP requests](/appsec/intro.md) from web servers.
-- The [Appsec](appsec/intro) feature is part of the Log Processor and filters HTTP Requests from the compatible web servers.
-- The [Local API](local_api/intro.md) acts as a middle man:
+- The [Log Processor](/log_processor/intro.mdx) handles detection. It analyzes logs from [various data sources](/log_processor/data_sources/introduction.md) and [HTTP requests](/appsec/intro.md) from compatible web servers.
+- The [Appsec](appsec/intro) feature is part of the Log Processor. It filters HTTP requests from compatible web servers.
+- The [Local API](local_api/intro.md) acts as a middleman:
- Between the [Log Processors](/log_processor/intro.mdx) and the [Remediation Components](/u/bouncers/intro) which are in charge of enforcing decisions.
- And with the [Central API](/central_api/intro.md) to share alerts and receive blocklists.
-- The [Remediation Components](/u/bouncers/intro) - also known as bouncers - block malicious IPs at your chosen level—whether via IpTables, firewalls, web servers, or reverse proxies. [See the full list on our CrowdSec Hub.](https://app.crowdsec.net/hub/remediation-components)
+- The [Remediation Components](/u/bouncers/intro) (also called bouncers) block malicious IPs at your chosen level—IpTables, firewalls, web servers, or reverse proxies. [See the full list on the CrowdSec Hub.](https://app.crowdsec.net/hub/remediation-components)
## Deployment options
-This architecture allows for both simple/standalone setups, or more distributed ones including as illustrated below:
+This architecture supports simple standalone setups and more distributed deployments:
-- Single machine ? Follow our [getting started guide](/u/getting_started/intro)
-- Multiple machines? Use the [distributed setup guide](/u/user_guides/multiserver_setup)
-- Already have a log pit (such as rsyslog or loki)? [Run crowdsec next to it](/u/user_guides/log_centralization), not on the production workloads
-- Running Kubernetes? Have a look at [our helm chart](/u/getting_started/installation/kubernetes)
-- Running containers? The [docker data source](/log_processor/data_sources/docker.md) might be what you need
-- Just looking for a WAF? Look at [our quickstart](appsec/intro)
+- Single machine: Follow the [getting started guide](/u/getting_started/intro).
+- Multiple machines: Use the [distributed setup guide](/u/user_guides/multiserver_setup).
+- Centralized logs (rsyslog, Loki, ...): [Run CrowdSec next to your log pipeline](/u/user_guides/log_centralization), not on production workloads.
+- Kubernetes: See [our Helm chart](/u/getting_started/installation/kubernetes).
+- Containers: Use the [Docker data source](/log_processor/data_sources/docker.md).
+- WAF only: Start with the [AppSec quickstart](appsec/intro).
Distributed architecture example:
diff --git a/crowdsec-docs/versioned_docs/version-v1.7/local_api/allowlists.md b/crowdsec-docs/versioned_docs/version-v1.7/local_api/allowlists.md
index 166e557eb..045897c24 100644
--- a/crowdsec-docs/versioned_docs/version-v1.7/local_api/allowlists.md
+++ b/crowdsec-docs/versioned_docs/version-v1.7/local_api/allowlists.md
@@ -6,10 +6,16 @@ sidebar_position: 7
# AllowLists
-The AllowLists feature in CrowdSec lets users manage IP-based allowlists at the LAPI level, affecting both local decisions and blocklist pulls. [Paying customers can also control AllowLists directly from the console for added convenience](/u/console/allowlists). This ensures greater flexibility in managing trusted IPs while maintaining CrowdSec’s robust security measures.
+The AllowLists feature in CrowdSec lets you manage IP-based allowlists at the LAPI level. It affects both local decisions and blocklist pulls, giving you more flexibility to trust specific IPs while keeping CrowdSec security controls in place.
+:::tip CrowdSec Premium: Centralized Console Management
-The AllowLists affect local decision and blocklist pulls in different ways:
+Premium users can manage AllowLists directly from the [CrowdSec Console](/u/console/allowlists), enabling centralized management across multiple Security Engines and Integrations. Console-managed allowlists require subscribing entities (Security Engines, Integrations, or Organizations) after creation.
+
+:::
+
+
+AllowLists affect local decisions and blocklist pulls in different ways:
| Area | Action | Real Time |
|-------|------|------|
@@ -19,14 +25,14 @@ The AllowLists affect local decision and blocklist pulls in different ways:
| cscli | Decision is blocked unless special flag is provided | ✅ |
-AllowLists are limited to IP/Range based rules. If you need rules that rely on log elements such as URL and so on, [Parser Whitelists](/log_processor/whitelist/introduction.md) or [Profile Rules](/local_api/profiles/format.md) might more relevant.
+AllowLists are limited to IP/range-based rules. If you need rules based on log elements (such as URLs), [Parser Whitelists](/log_processor/whitelist/introduction.md) or [Profile Rules](/local_api/profiles/format.md) might be more relevant.
-### Creating an allowlist
+## Creating an allowlist
-Allowlists creation is done with `cscli allowlists create`, for example: `cscli allowlists create my_allowlistd -d safe_ips`.
+Create an allowlist with `cscli allowlists create`, for example: `cscli allowlists create my_allowlist -d safe_ips`.
-The `-d` parameter is mandatory, it's a description for the allowlist for future reference:
+The `-d` flag is mandatory. It sets a description for future reference:
```bash
$ cscli allowlists create my_allowlist --description "test allowlist"
allowlist 'my_allowlist' created successfully
@@ -34,20 +40,20 @@ allowlist 'my_allowlist' created successfully
This command must be run on the LAPI.
-### Adding entries to an allowlist
+## Adding entries to an allowlist
-Adding new entries to an allowlist is done with `cscli allowlists add
+
+
+#### Step 2: Pick a representative log line
+
+From the alert details, pick one triggering log line. You will use the raw line with `cscli explain` in the next step.
+
+#### Step 3: Use `cscli explain` to reveal parsed fields
+
+To write a safe whitelist, use the exact field names and values available at parse/enrich time.
+
+Run `cscli explain` against the log line:
+
```bash
-tail -f /var/log/crowdsec.log
+sudo cscli explain \
+ --log 'Example: Alert inspection output
```bash -nikto -host myfqdn.com +$ cscli alerts inspect 176012 -d + +################################################################################################ + + - ID : 176012 + - Date : 2026-01-07T15:11:08Z + - Machine : testMachine + - Simulation : false + - Remediation : true + - Reason : crowdsecurity/http-crawl-non_statics + - Events Count : 44 + - Scope:Value : Ip:192.168.1.100 + - Country : US + - AS : EXAMPLE-AS-BLOCK + - Begin : 2026-01-07T15:11:05Z + - End : 2026-01-07T15:11:07Z + - UUID : 0061339c-f070-4859-8f2a-66249c709d73 + +╭────────────────────────────────────────────────────────────────────────────╮ +│ Active Decisions │ +├───────────┬───────────────────┬────────┬────────────┬──────────────────────┤ +│ ID │ scope:value │ action │ expiration │ created_at │ +├───────────┼───────────────────┼────────┼────────────┼──────────────────────┤ +│ 905003939 │ Ip:192.168.1.100 │ ban │ 23h35m33s │ 2026-01-07T15:11:08Z │ +╰───────────┴───────────────────┴────────┴────────────┴──────────────────────╯ + + - Context : +╭────────────┬────────────╮ +│ Key │ Value │ +├────────────┼────────────┤ +│ method │ GET │ +│ status │ 404 │ +│ target_uri │ /lanz.php │ +│ target_uri │ /xwpg.php │ +│ target_uri │ /slsqc.php │ +│ target_uri │ /fs8.php │ +│ target_uri │ /flap.php │ +│ target_uri │ /ws34.php │ +│ user_agent │ - │ +╰────────────┴────────────╯ + + - Events : + +- Date: 2026-01-07 15:11:07 +0000 UTC +╭─────────────────┬─────────────────────────────╮ +│ Key │ Value │ +├─────────────────┼─────────────────────────────┤ +│ ASNNumber │ 64512 │ +│ ASNOrg │ EXAMPLE-AS-BLOCK │ +│ IsInEU │ false │ +│ IsoCode │ US │ +│ SourceRange │ 192.168.0.0/16 │ +│ datasource_path │ /var/log/nginx/access.log │ +│ datasource_type │ file │ +│ http_args_len │ 0 │ +│ http_path │ /lanz.php │ +│ http_status │ 404 │ +│ http_user_agent │ - │ +│ http_verb │ GET │ +│ log_type │ http_access-log │ +│ service │ http │ +│ source_ip │ 192.168.1.100 │ +│ target_fqdn │ example.com │ +│ timestamp │ 2026-01-07T15:11:07Z │ +╰─────────────────┴─────────────────────────────╯ + +- Date: 2026-01-07 15:11:07 +0000 UTC +╭─────────────────┬─────────────────────────────╮ +│ Key │ Value │ +├─────────────────┼─────────────────────────────┤ +│ ASNNumber │ 64512 │ +│ ASNOrg │ EXAMPLE-AS-BLOCK │ +│ IsInEU │ false │ +│ IsoCode │ US │ +│ SourceRange │ 192.168.0.0/16 │ +│ datasource_path │ /var/log/nginx/access.log │ +│ datasource_type │ file │ +│ http_args_len │ 0 │ +│ http_path │ /xwpg.php │ +│ http_status │ 404 │ +│ http_user_agent │ - │ +│ http_verb │ GET │ +│ log_type │ http_access-log │ +│ service │ http │ +│ source_ip │ 192.168.1.100 │ +│ target_fqdn │ example.com │ +│ timestamp │ 2026-01-07T15:11:07Z │ +╰─────────────────┴─────────────────────────────╯ ``` +In this example, the events section lists keys such as `http_path`, `http_status`, `http_verb`, and `source_ip`. Those keys map to `evt.Meta.*` fields you can use in your whitelist expressions. For instance, `http_path` becomes `evt.Meta.http_path`. + +
-
+## Create the parser whitelist file
+
+Once you have identified the fields you want to use, create a new YAML file in the appropriate directory. See the [introduction](/log_processor/whitelist/introduction.md) for OS-specific paths.
+
+For example:
+
+```bash
+sudo nano /etc/crowdsec/parsers/s02-enrich/zz-whitelist-myapp.yaml
+```
+
+### Example 1: Whitelist by user-agent
+
+```yaml
+name: "myorg/whitelist-healthcheck-ua"
+description: "Ignore our synthetic checks user-agent"
+whitelist:
+ reason: "synthetic monitoring"
+ expression:
+ - evt.Parsed.http_user_agent == 'MyHealthcheckBot/1.0'
+```
+
+### Example 2: Whitelist a specific endpoint (health check)
+
+Use values you confirmed via `cscli explain`:
+
+```yaml
+name: "myorg/whitelist-healthz"
+description: "Ignore health checks hitting /healthz"
+whitelist:
+ reason: "health endpoint"
+ expression:
+ - evt.Meta.http_path == '/healthz' and evt.Meta.http_verb == 'GET'
+```
+
+:::tip
+
+Keep whitelist expressions as narrow as possible (path + verb + optional user-agent) to avoid hiding real attacks.
+
+:::
+
+### Example 3: Whitelist by multiple conditions
+
+You can combine conditions:
+
+```yaml
+name: "myorg/whitelist-acme-challenge"
+description: "Ignore ACME challenge requests"
+whitelist:
+ reason: "legitimate certificate renewal"
+ expression:
+ - evt.Meta.http_path startsWith '/.well-known/acme-challenge/' and evt.Meta.http_verb == 'GET'
+```
+
+### Example 4: Whitelist by status code and path
+
+```yaml
+name: "myorg/whitelist-monitoring"
+description: "Ignore monitoring tool requests"
+whitelist:
+ reason: "internal monitoring"
+ expression:
+ - evt.Meta.http_path == '/metrics' and evt.Meta.http_status == '200'
+```
+
+### Real-world example: Nextcloud
+
+For a real-world example of expression-based whitelists, see the [Nextcloud whitelist example on the Hub](https://hub.crowdsec.net/author/crowdsecurity/configurations/nextcloud-whitelist), which shows how to whitelist common Nextcloud endpoints and patterns.
+
+## Reload CrowdSec and validate
+
+Reload CrowdSec to apply the new parser whitelist:
+
+```bash
+sudo systemctl reload crowdsec
+```
+
+Then validate in two ways:
+
+1. **Re-run `cscli explain`** on the same triggering line and confirm it is discarded/whitelisted. CrowdSec logs when lines are discarded because they match a whitelist.
+
+2. **Confirm new decisions are no longer created** for the same pattern/IP:
+
+```bash
+sudo cscli decisions list --ip