Merge pull request #104 from julienloizelet/feat/tls-auth

Feat/tls auth

Author: julienloizelet

.github/workflows/test-suite.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Install DDEV
         env:
-          DDEV_VERSION: v1.19.3
+          DDEV_VERSION: v1.20.0
         run: |
           # @see https://ddev.readthedocs.io/en/stable/#installationupgrade-script-linux-and-macos-armarm64-and-amd64-architectures
           sudo apt-get -qq update
@@ -55,6 +55,9 @@ jobs:
           cp .ddev/config_overrides/config.${{ env.PHP_VERSION_CODE }}.yaml .ddev/config.${{ env.PHP_VERSION_CODE }}.yaml
           cp .ddev/additional_docker_compose/docker-compose.crowdsec.yaml .ddev/docker-compose.crowdsec.yaml
           cp .ddev/additional_docker_compose/docker-compose.playwright.yaml .ddev/docker-compose.playwright.yaml
+          mkdir ${{ github.workspace }}/cfssl
+          cp -r .ddev/custom_files/crowdsec/cfssl/* ${{ github.workspace }}/cfssl
+          ls -l ${{ github.workspace }}/cfssl
           ddev start
 
       - name: Set BOUNCER_KEY and PROXY_IP env
@@ -83,7 +86,6 @@ jobs:
 
       - name: Prepare PHP UNIT tests
         run: |
-          ddev create-watcher PhpUnitTestMachine PhpUnitTestMachinePassword
           ddev maxmind-download DEFAULT GeoLite2-City /var/www/html/${{env.EXTENSION_PATH}}/tests
           ddev maxmind-download DEFAULT GeoLite2-Country /var/www/html/${{env.EXTENSION_PATH}}/tests
           cd ${{env.EXTENSION_PATH}}/tests
@@ -95,23 +97,26 @@ jobs:
 
       - name: Run "IP verification with file_get_contents" test
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php
 
       - name: Run "IP verification with cURL" test
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} USE_CURL=1 LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl USE_CURL=1 LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php
+
+      - name: Run "IP verification with TLS" test
+        run: |
+          ddev exec AGENT_TLS_PATH=/var/www/html/cfssl BOUNCER_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/IpVerificationTest.php    
 
       - name: Run "Geolocation with file_get_contents" test
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080  /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/GeolocationTest.php
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080  /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/GeolocationTest.php
 
       - name: Run "Geolocation with cURL" test
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} USE_CURL=1 LAPI_URL=http://crowdsec:8080  /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/GeolocationTest.php    
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} AGENT_TLS_PATH=/var/www/html/cfssl USE_CURL=1 LAPI_URL=https://crowdsec:8080  /usr/bin/php ./${{env.EXTENSION_PATH}}/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./${{env.EXTENSION_PATH}}/tests/Integration/GeolocationTest.php    
 
       - name: Prepare Standalone Bouncer end-to-end tests
         run: |
-          ddev create-watcher
           cd ${{ github.workspace }}/.ddev
           ddev nginx-config custom_files/crowdsec-prepend-nginx-site.conf
           cd ${{ github.workspace }}
@@ -215,4 +220,27 @@ jobs:
           sed -i  's/\x27stream_mode\x27 => true/\x27stream_mode\x27 => false/g' scripts/auto-prepend/settings.php
           cat scripts/auto-prepend/settings.php
           cd ${{ github.workspace }}/${{env.EXTENSION_PATH}}/tests/end-to-end/__scripts__
-          ./run-tests.sh ci "./__tests__/1-live-mode.js"
+          ./run-tests.sh ci "./__tests__/1-live-mode.js"
+
+      - name: Run "live mode with TLS auth" test
+        run: |
+          cd ${{ github.workspace }}/${{env.EXTENSION_PATH}}
+          sed -i  's/\x27auth_type\x27 => \x27api_key\x27/\x27auth_type\x27 => \x27tls\x27/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27api_key\x27 => \x27${{env.BOUNCER_KEY}}\x27/\x27api_key\x27 => \x27\x27/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27tls_cert_path\x27 => \x27\x27/\x27tls_cert_path\x27 => \x27\/var\/www\/html\/cfssl\/bouncer.pem\x27/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27tls_key_path\x27 => \x27\x27/\x27tls_key_path\x27 => \x27\/var\/www\/html\/cfssl\/bouncer-key.pem\x27/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27tls_ca_cert_path\x27 => \x27\x27/\x27tls_ca_cert_path\x27 => \x27\/var\/www\/html\/cfssl\/ca-chain.pem\x27/g' scripts/auto-prepend/settings.php
+          cat scripts/auto-prepend/settings.php
+          cd ${{ github.workspace }}/${{env.EXTENSION_PATH}}/tests/end-to-end/__scripts__
+          ./run-tests.sh ci "./__tests__/1-live-mode.js"
+          
+
+      - name: Run "stream mode with TLS auth and cURL" test
+        run: |
+          cd ${{ github.workspace }}/${{env.EXTENSION_PATH}}
+          sed -i  's/\x27stream_mode\x27 => false/\x27stream_mode\x27 => true/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27forced_test_forwarded_ip\x27 => \x27${{env.IPV6_TEST_IP}}\x27/\x27forced_test_forwarded_ip\x27 => \x27\x27/g' scripts/auto-prepend/settings.php
+          sed -i  's/\x27use_curl\x27 => false/\x27use_curl\x27 => true/g' scripts/auto-prepend/settings.php
+          cat scripts/auto-prepend/settings.php
+          cd ${{ github.workspace }}/${{env.EXTENSION_PATH}}/tests/end-to-end/__scripts__
+          ./run-tests.sh ci "./__tests__/3-stream-mode.js"

CHANGELOG.md

@@ -5,11 +5,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 
+## [0.29.0] - 2022-08-11
+
+### Added
+- Add TLS connection feature
+
+
 ## [0.28.0] - 2022-08-04
 
 ### Changed
 - *Breaking change*: Rename `ClientAbstract` class to `AbstractClient`
-- Hide `api_key` in log.
+- Hide `api_key` in log
 
 ### Added
 - Add `disable_prod_log` configuration 

docs/DEVELOPER.md

@@ -72,14 +72,14 @@ For a quick start, follow the below steps.
 
 #### DDEV installation
 
-This project is fully compatible with DDEV 1.19.3, and it is recommended to use this specific version.
+This project is fully compatible with DDEV 1.20.0, and it is recommended to use this specific version.
 For the DDEV installation, please follow the [official instructions](https://ddev.readthedocs.io/en/stable/#installation).
 On a Linux distribution, you can run:
 ```
 sudo apt-get -qq update
 sudo apt-get -qq -y install libnss3-tools
 curl -LO https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh
-bash install_ddev.sh v1.19.3
+bash install_ddev.sh v1.20.0
 rm install_ddev.sh
 ```
 
@@ -167,6 +167,8 @@ It will return the bouncer key.
 ddev create-watcher [name] [password]
 ```
 
+N.B : Since we are using TLS authentification for agent, you should avoid to create a watcher with this method.
+
 
 #### Use composer to update or install the lib
 
@@ -205,17 +207,20 @@ First, create a bouncer and keep the result key.
 ddev create-bouncer
 ```
 
-Then, create a specific watcher for unit test:
-
+Then, as we use a TLS ready CrowdSec container, you have to copy some certificates and key:
+  
 ```bash
-ddev create-watcher PhpUnitTestMachine PhpUnitTestMachinePassword
+cd php-project-sources
+mkdir cfssl
+cp -r ../.ddev/custom_files/crowdsec/cfssl/* cfssl
 ```
 
 Finally, run
 
 
 ```bash
-ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
+ddev exec BOUNCER_KEY=your-bouncer-key AGENT_TLS_PATH=/var/www/html/cfssl LAPI_URL=http://crowdsec:8080 
+MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
 ```
 
 For geolocation Unit Test, you should first put 2 free MaxMind databases in the `tests` folder : `GeoLite2-City.mmdb`
@@ -225,8 +230,18 @@ and`GeoLite2-Country.mmdb`. You can download these databases by creating a maxmi
 Then, you can run:
 
 ```bash
-ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080  /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/GeolocationTest.php
+ddev exec BOUNCER_KEY=your-bouncer-key AGENT_TLS_PATH=/var/www/html/cfssl LAPI_URL=http://crowdsec:8080  
+/usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/GeolocationTest.php
+```
 
+**N.B**: If you want to test with `curl` instead of `file_get_contents` calls to LAPI, you have to add `USE_CURL=1` in 
+the previous commands.
+
+**N.B**: If you want to test with `tls` authentification, you have to add `BOUNCER_TLS_PATH` environment varibale 
+and specify the path where you store certificates and keys. For example:
+
+```bash
+ddev exec USE_CURL=1 AGENT_TLS_PATH=/var/www/html/cfssl  BOUNCER_TLS_PATH=/var/www/html/cfssl LAPI_URL=https://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
 ```
 
 

docs/USER_GUIDE.md

@@ -119,82 +119,136 @@ Here is the list of available settings:
 
 ##### LAPI Connection
 
-- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`
+- `auth_type`: Select from `api_key` and `tls`. Choose if you want to use an API-KEY or a TLS (pki) authentification.
+  TLS authentication is only available if you use CrowdSec agent with a version superior to 1.4.0.
+
+
+- `api_key`: Key generated by the cscli (CrowdSec cli) command like `cscli bouncers add bouncer-php-library`.
+  Only required if you choose `api_key` as `auth_type`.
+
+
+- `tls_cert_path`: absolute path to the bouncer certificate (e.g. pem file).
+  Only required if you choose `tls` as `auth_type`.
+
+
+- `tls_key_path`: Absolute path to the bouncer key (e.g. pem file).
+  Only required if you choose `tls` as `auth_type`.
+
+
+- `tls_verify_peer`: This option determines whether request handler verifies the authenticity of the peer's certificate.
+  Only required if you choose `tls` as `auth_type`. 
+  When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity.
+  If `tls_verify_peer` is set to true, request handler verifies whether the certificate is authentic.
+  This trust is based on a chain of digital signatures,
+  rooted in certification authority (CA) certificates you supply using the `tls_ca_cert_path` setting below.
+
+
+- `tls_ca_cert_path`: Absolute path to the CA used to process peer verification.
+  Only required if you choose `tls` as `auth_type` and `tls_verify_peer` is set to true.
+
 
 - `api_url`: Define the URL to your LAPI server, default to `http://localhost:8080`.
 
+
 - `api_timeout`: In seconds. The timeout when calling LAPI. Must be greater or equal than 1. Default to 1 sec.
 
+
 - `use_curl`: By default, this lib call the REST LAPI using `file_get_contents` method (`allow_url_fopen` is required).
   You can set `use_curl` to `true` in order to use `cURL` request instead (`curl` is in then required)
 
+
 ##### Debug
 - `debug_mode`: `true` to enable verbose debug log. Default to `false`.
 
+
 - `disable_prod_log`: `true` to disable prod log. Default to `false`.
 
-- `log_directory_path`: Absolute path to store log files. Important note: be sur this path won't be publicly accessible
+
+- `log_directory_path`: Absolute path to store log files. Important note: be sur this path won't be publicly 
+  accessible.
+
 
 - `display_errors`: true to stop the process and display errors on browser if any.
 
+
 - `forced_test_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used instead of the 
   real remote ip.
 
+
 - `forced_test_forwarded_ip`: Only for test or debug purpose. Default to empty. If not empty, it will be used 
   instead of the real forwarded ip. If set to `no_forward`, the x-forwarded-for mechanism will not be used at all.
 
 ##### Bouncer behavior
 
 - `bouncing_level`:  Select from `bouncing_disabled`, `normal_bouncing` or `flex_bouncing`. Choose if you want to apply CrowdSec directives (Normal bouncing) or be more permissive (Flex bouncing). With the `Flex mode`, it is impossible to accidentally block access to your site to people who don’t deserve it. This mode makes it possible to never ban an IP but only to offer a Captcha, in the worst-case scenario.
 
+
 - `fallback_remediation`: Select from `bypass` (minimum remediation), `captcha` or `ban` (maximum remediation). Default to 'captcha'. Handle unknown remediations as.
 
+
 - `max_remediation_level`: Select from `bypass`,`captcha` or `ban`. Default to 'ban'. Cap the 
   remediation to the selected one.
 
+
 - `trust_ip_forward_array`:  If you use a CDN, a reverse proxy or a load balancer, set an array of IPs. For other IPs, the bouncer will not trust the X-Forwarded-For header.
 
-- `excluded_uris`: array of URIs that will not be bounced
+
+- `excluded_uris`: array of URIs that will not be bounced.
 
 ##### Cache
 
 - `cache_system`: Select from `phpfs` (File system cache), `redis` or `memcached`.
 
+
 - `fs_cache_path`: Will be used only if you choose File system as cache_system. Important note: be sur this path 
   won't be publicly accessible.
 
-- `redis_dsn`:   Will be used only if you choose Redis cache as cache_system
 
-- `memcached_dsn`: Will be used only if you choose Memcached as cache_system
+- `redis_dsn`:   Will be used only if you choose Redis cache as cache_system.
+
+
+- `memcached_dsn`: Will be used only if you choose Memcached as cache_system.
+
 
 - `clean_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5.
 
+
 - `bad_ip_cache_duration`: Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20.
 
+
 - `captcha_cache_duration`: Set the duration we keep in cache the captcha flow variables for an IP. In seconds. 
   Defaults to 86400.. In seconds. Defaults to 20.
 
+
 - `geolocation_cache_duration`: Set the duration we keep in cache a geolocation result for an IP . In seconds. 
   Defaults to 86400. Depends on the below `geolocation[save_result]` configuration.
 
+
 - `stream_mode`: true to enable stream mode, false to enable the live mode. Default to false. By default, the `live mode` is enabled. The first time a stranger connects to your website, this mode means that the IP will be checked directly by the CrowdSec API. The rest of your user’s browsing will be even more transparent thanks to the fully customizable cache system. But you can also activate the `stream mode`. This mode allows you to constantly feed the bouncer with the malicious IP list via a background task (CRON), making it to be even faster when checking the IP of your visitors. Besides, if your site has a lot of unique visitors at the same time, this will not influence the traffic to the API of your CrowdSec instance.
 
 ##### Geolocation
 
 - `geolocation`: Settings for geolocation remediation (i.e. country based remediation).
+
 - `geolocation[enabled]`: true to enable remediation based on country. Default to false.
-- `geolocation[type]`:  Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`
+
+- `geolocation[type]`:  Geolocation system. Only 'maxmind' is available for the moment. Default to `maxmind`.
+
 
 - `geolocation[save_result]`: true to store the geolocalized country in cache. Default to true. Setting true 
-  will avoid multiple call to the geolocalized system (e.g. maxmind database)
-- `geolocation[maxmind]`: MaxMind settings
+  will avoid multiple call to the geolocalized system (e.g. maxmind database).
+
+- `geolocation[maxmind]`: MaxMind settings.
+
 - `geolocation[maxmind][database_type]`: Select from `country` or `city`. Default to `country`. These are the two available MaxMind database types.
-- `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (mmdb 
+
+- `geolocation[maxmind][database_path]`: Absolute path to the MaxMind database (e.g. mmdb file)
 
 
 ##### Captcha and ban wall settings
 
 - `hide_mentions`: true to hide CrowdSec mentions on ban and captcha walls.
+
 - Wording and css settings: 
 
   `theme_color_text_primary`

scripts/auto-prepend/bounce.php

@@ -16,5 +16,4 @@
 }elseif($crowdSecStandaloneBouncerConfig['bouncing_level'] === 'flex_boucing'){
     $crowdSecStandaloneBouncerConfig['bouncing_level'] = 'flex_bouncing';
 }
-
 $bounce->safelyBounce($crowdSecStandaloneBouncerConfig);