Skip to main content
Version: v1.6.0

Protocol

warning

This section is only relevant if you want to add support for the CrowdSec application security component in your own remediation component or directly at the application level.

Introduction

To interact with the CrowdSec application security component, a protocol need to be respected.

The application security component expect some headers to be present in the HTTP request (in addition to the original HTTP headers and body) and according to the result, the application security component will respond differently.

This documentation can be useful in case you want to write your own remediation component that interact with the CrowdSec application security component, or if you want to improve your existing one.

HTTP Headers

To work with the CrowdSec application security component, some HTTP headers are require, in addition to the other HTTP headers and the body of the original request.

Header NameDescription
X-Crowdsec-Appsec-IpThe Real IP address of the original HTTP request
X-Crowdsec-Appsec-UriThe URI of the original HTTP request
X-Crowdsec-Appsec-HostThe Host of the original HTTP request
X-Crowdsec-Appsec-VerbThe Method of the original HTTP request
X-Crowdsec-Appsec-Api-KeyThe API Key to communicate with the CrowdSec application security component
X-Crowdsec-Appsec-User-AgentThe User-Agent of the original HTTP request
info

X-Crowdsec-Appsec-User-Agent was introduced in version 1.6.1 moving forward this header should be supplied by the Remediation Component for the AppSec Component to handle client useragents properly

note

All requests forwarded by the remediation component must be sent via a GET request. However, if the HTTP request contains a body, a POST request must be sent to the Application Security Component.

Example

For this example:

  • A POST HTTP request has been made by the IP 1.2.3.4 to a website on example.com.
  • The Application Security Component listen on http://localhost:4241/.
Original HTTP Request
POST /login HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:68.0) Gecko/20100101 Firefox/68.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded
Content-Length: 73
Connection: keep-alive
Upgrade-Insecure-Requests: 1

username=admin' OR '1'='1' -- &password=password

HTTP Request sent to the application security component
POST / HTTP/1.1
Host: localhost:4241
X-Crowdsec-Appsec-ip: 1.2.3.4
X-Crowdsec-Appsec-Uri: /login
X-Crowdsec-Appsec-Host: example.com
X-Crowdsec-Appsec-Verb: POST
X-Crowdsec-Appsec-Api-Key: <API_KEY>
X-Crowdsec-Appsec-User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:68.0) Gecko/20100101 Firefox/68.0
User-Agent: lua-resty-http/0.17.1 (Lua) ngx_lua/10026
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded
Content-Length: 73
Connection: keep-alive
Upgrade-Insecure-Requests: 1

username=admin' OR '1'='1' -- &password=password

Response Code

According to the result of the processing of the HTTP request, the application security component will respond with a different HTTP code and body.

HTTP CodeDescriptionBody
200The HTTP request is allowed{"action" : "allow"}
403The HTTP request triggered one or more application security component rules{"action" : "ban", "http_status": 403} or {"action" : "captcha", "http_status": 403}
500An error occurred in the application security component. The remediation component must support a APPSEC_FAILURE_ACTION parameter to handle this casenull
401The remediation component is not authenticated. It must use the same API Key that was generated to pull the local API requestnull

In case of a 403 response, the body will contain the action to take and the HTTP status code to return to the client.