✨ feat(logs) add supports write logs to files (#217)

* ✨ feat(logs) add supports write logs to files * fix(lint) 🚨 fix go lint * 🐛 fix(bug) check path is done only if provided * 📝 doc(vars) add LogFilePath to vars * 🦺 chore(review) update doc, configuration check and logger
2025-11-08 15:15:05 +01:00 · 2025-03-31 20:19:44 +02:00
parent a184ae6db9
commit 5418d35feb
7 changed files with 110 additions and 61 deletions
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -25,27 +25,27 @@ linters-settings:
    rules:
      Main:
        files:
-        - $all
-        - "!$test"
+          - $all
+          - "!$test"
        allow:
-        - $gostd
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/logger
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/ip
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/configuration
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/cache
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/captcha
-        - github.com/leprosus/golang-ttl-map
-        - github.com/maxlerebourg/simpleredis
+          - $gostd
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/logger
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/ip
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/configuration
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/cache
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/captcha
+          - github.com/leprosus/golang-ttl-map
+          - github.com/maxlerebourg/simpleredis
      Test:
        files:
-        - $test
+          - $test
        allow:
-        - $gostd
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/logger
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/ip
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/configuration
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/cache
-        - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/captcha
+          - $gostd
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/logger
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/ip
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/configuration
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/cache
+          - github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin/pkg/captcha

 linters:
  enable-all: true
@@ -72,7 +72,7 @@ linters:
    - gofumpt
    - gci
    - mnd
-
+    - exportloopref
 issues:
  exclude-use-default: false
  max-same-issues: 0
--- a/README.md
+++ b/README.md
@@ -26,34 +26,35 @@ The AppSec Component offers:
 - Low-effort virtual patching capabilities.
 - Support for your legacy ModSecurity rules.
 - Combining classic WAF benefits with advanced CrowdSec features for otherwise difficult advanced behavior detection.
+
 More information on appsec in the [Crowdsec Documentation](https://doc.crowdsec.net/docs/next/appsec/intro/).

 Remediation offered by [Crowdsec](https://docs.crowdsec.net/u/bouncers/intro) and supported by the plugin can be either `ban` or `captcha`.  
 For the `ban` remediation the user will be blocked in Traefik (HTTP 403).  
-For the `captcha` remediation, the user will be redirected to a page to complete a captcha challenge.  
+For the `captcha` remediation, the user will be redirected to a page to complete a captcha challenge.

 On successfull completion, he will be cleaned for a specified period of time before a new resolution challenge is expected if Crowdsec still has a decision to verify the user behavior. See the example captcha for more informations and configuration intructions.  
 The following captcha providers are supported now:
- - [hcaptcha](https://www.hcaptcha.com/)
- - [recaptcha](https://www.google.com/recaptcha/about/)
- - [turnstile](https://www.cloudflare.com/products/turnstile/)

+- [hcaptcha](https://www.hcaptcha.com/)
+- [recaptcha](https://www.google.com/recaptcha/about/)
+- [turnstile](https://www.cloudflare.com/products/turnstile/)

 There are 5 operating modes (CrowdsecMode) for this plugin:

-| Mode | Description |
-|------|------|
-| none | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual. All request call the Crowdsec LAPI |
-| live | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual.    The bouncer can leverage use of a local cache in order to reduce the number of requests made to the Crowdsec LAPI. It will keep in cache the status for each IP that makes queries. |
-| stream | Stream Streaming mode allows you to keep in the local cache only the Banned IPs, every requests that does not hit the cache is authorized. Every minute, the cache is updated with news from the Crowdsec LAPI. |
-| alone | Standalone mode, similar to the streaming mode but the blacklisted IPs are fetched on the CAPI. Every 2 hours, the cache is updated with news from the Crowdsec CAPI. It does not include any locally banned IP, but can work without a crowdsec service. |
-| appsec | Disable Crowdsec IP checking but apply Crowdsec Appsec checking. This mode is intended to be used when Crowdsec IP checking is applied at the Firewall Level. |
+| Mode   | Description                                                                                                                                                                                                                                                                                           |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| none   | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual. All request call the Crowdsec LAPI                                                                                                                                                  |
+| live   | If the client IP is on ban list, it will get a http code 403 response. Otherwise, request will continue as usual. The bouncer can leverage use of a local cache in order to reduce the number of requests made to the Crowdsec LAPI. It will keep in cache the status for each IP that makes queries. |
+| stream | Stream Streaming mode allows you to keep in the local cache only the Banned IPs, every requests that does not hit the cache is authorized. Every minute, the cache is updated with news from the Crowdsec LAPI.                                                                                       |
+| alone  | Standalone mode, similar to the streaming mode but the blacklisted IPs are fetched on the CAPI. Every 2 hours, the cache is updated with news from the Crowdsec CAPI. It does not include any locally banned IP, but can work without a crowdsec service.                                             |
+| appsec | Disable Crowdsec IP checking but apply Crowdsec Appsec checking. This mode is intended to be used when Crowdsec IP checking is applied at the Firewall Level.                                                                                                                                         |

 The `streaming mode` is recommended for performance, decisions are updated every 60 sec by default and that's the only communication between Traefik and Crowdsec. Every request that happens hits the cache for quick decisions.

-The cache can be local to Traefik in memory or using a separate Redis instance.  
+The cache can be local to Traefik in memory or using a separate Redis instance.

-Below are Mermaid diagrams detailling how each mode work:  
+Below are Mermaid diagrams detailling how each mode work:

 <details><summary>Mode none workflow</summary>

@@ -283,7 +284,7 @@ sequenceDiagram
    User->>TraefikPlugin: Fine, done!
    create participant ProviderCaptcha
    TraefikPlugin-->>ProviderCaptcha: Is the validation OK ?
-    Destroy ProviderCaptcha    
+    Destroy ProviderCaptcha
    ProviderCaptcha-->>TraefikPlugin: Yes
    TraefikPlugin-->>PluginCache: Set the User IP Clean for captchaGracePeriodSeconds
    Destroy PluginCache
@@ -300,6 +301,7 @@ sequenceDiagram
 To get started, use the `docker-compose.yml` file.

 You can run it with:
+
 ```bash
 make run
 ```
@@ -307,20 +309,26 @@ make run
 ### Note

 **/!\ Cache is shared by all services**
-*This means if an IP is banned, all services which are protected by an instance of the plugin will deny requests from that IP*
-Only one instance of the plugin is *possible*.
+_This means if an IP is banned, all services which are protected by an instance of the plugin will deny requests from that IP_
+Only one instance of the plugin is _possible_.

 **/!\ Appsec maximum body limit is defaulted to 10MB**
-*By careful when you upgrade to >1.4.x*
+_By careful when you upgrade to >1.4.x_

 ### Variables
+
 - Enabled
  - bool
  - default: false
  - Enable the plugin
 - LogLevel
  - string
-  - default: `INFO`, expected values are: `INFO`, `DEBUG`, `ERROR`, log are written to `stdout` / `stderr`
+  - default: `INFO`, expected values are: `INFO`, `DEBUG`, `ERROR`
+  - Log are written to `stdout` / `stderr` of file if LogFilePath is provided
+- LogFilePath
+  - string
+  - default: ""
+  - File Path to write logs, must be writable by Traefik, Log rotation may require a restart of traefik
 - CrowdsecMode
  - string
  - default: `live`, expected values are: `none`, `live`, `stream`, `alone`, `appsec`
@@ -362,7 +370,7 @@ Only one instance of the plugin is *possible*.
 - CrowdsecLapiKey
  - string
  - default: ""
-  - Crowdsec LAPI key for the bouncer. 
+  - Crowdsec LAPI key for the bouncer.
 - CrowdsecLapiTlsInsecureVerify
  - bool
  - default: false
@@ -380,7 +388,7 @@ Only one instance of the plugin is *possible*.
  - default: ""
  - PEM-encoded client private key of the Bouncer
 - ClientTrustedIPs
-  - string 
+  - string
  - default: []
  - List of client IPs to trust, they will bypass any check from the bouncer or cache (useful for LAN or VPN IP)
 - RemediationHeadersCustomName
@@ -400,15 +408,15 @@ Only one instance of the plugin is *possible*.
  - default: false
  - enable Redis cache instead of in-memory cache
 - RedisCacheHost
-  - string 
+  - string
  - default: "redis:6379"
  - hostname and port for the Redis service
 - RedisCachePassword
-  - string 
+  - string
  - default: ""
  - Password for the Redis service
 - RedisCacheDatabase
-  - string 
+  - string
  - default: ""
  - Database selection for the Redis service
 - RedisUnreachableBlock
@@ -467,6 +475,7 @@ Only one instance of the plugin is *possible*.
 For each plugin, the Traefik static configuration must define the module name (as is usual for Go packages).

 The following declaration (given here in YAML) defines a plugin:
+
 > Note that you don't need to copy all thoses settings but only the ones you want to use.  
 > See the examples for advanced usage.

@@ -498,13 +507,14 @@ http:
      loadBalancer:
        servers:
          - url: http://127.0.0.1:5000
-  
+
  middlewares:
    crowdsec:
      plugin:
        bouncer:
          enabled: false
          logLevel: DEBUG
+          LogFilePath: ""
          updateIntervalSeconds: 60
          updateMaxFailure: 0
          defaultDecisionSeconds: 60
@@ -528,10 +538,10 @@ http:
            - crowdsecurity/http-path-traversal-probing
            - crowdsecurity/http-xss-probing
            - crowdsecurity/http-generic-bf
-          forwardedHeadersTrustedIPs: 
+          forwardedHeadersTrustedIPs:
            - 10.0.10.23/32
            - 10.0.20.0/24
-          clientTrustedIPs: 
+          clientTrustedIPs:
            - 192.168.1.0/24
          forwardedHeadersCustomName: X-Custom-Header
          remediationHeadersCustomName: cs-remediation
@@ -575,9 +585,10 @@ http:
 `CrowdsecLapiTlsCertificateBouncerKey`, `CrowdsecLapiTlsCertificateBouncer`, `CrowdsecLapiTlsCertificateAuthority`, `CrowdsecCapiMachineId`, `CrowdsecCapiPassword`, `CrowdsecLapiKey`, `CaptchaSiteKey` and `CaptchaSecretKey` can be provided with the content as raw or through a file path that Traefik can read.  
 The file variable will be used as preference if both content and file are provided for the same variable.

-Format is:  
+Format is:
+
 - Content: VariableName: XXX
- File   : VariableNameFile: /path
+- File : VariableNameFile: /path

 #### Authenticate with LAPI

@@ -585,6 +596,7 @@ You can authenticate to the LAPI either with LAPIKEY or by using client certific
 Please see below for more details on each option.

 #### Generate LAPI KEY
+
 You can generate a crowdsec API key for the LAPI.  
 You can follow the documentation here: [docs.crowdsec.net/docs/user_guides/lapi_mgmt](https://docs.crowdsec.net/docs/user_guides/lapi_mgmt)

@@ -594,24 +606,26 @@ docker exec crowdsec cscli bouncers add crowdsecBouncer
 ```

 This LAPI key must be set where is noted FIXME-LAPI-KEY in the docker-compose.yml
+
 ```yaml
-...
+..
 whoami:
  labels:
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapikey=FIXME-LAPI-KEY"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapischeme=http"
    - "traefik.http.middlewares.crowdsec.plugin.bouncer.crowdseclapihost=crowdsec:8080"
-...
+..
 crowdsec:
  environment:
    BOUNCER_KEY_TRAEFIK: FIXME-LAPI-KEY
-...
 ```

 Note:
+
 > Crowdsec does not require a specific format for la LAPI-key, you may use something like FIXME-LAPI-KEY but that is not recommanded for obvious reasons

 You can then run all the containers:
+
 ```bash
 docker compose up -d
 ```
@@ -637,7 +651,7 @@ Please see the [tls-auth example](https://github.com/maxlerebourg/crowdsec-bounc
 docker compose up -d crowdsec
 docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m # this will be effective 10min
 docker exec crowdsec cscli decisions remove --ip 10.0.0.10
-docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m -t captcha # this will return a captcha challenge  
+docker exec crowdsec cscli decisions add --ip 10.0.0.10 -d 10m -t captcha # this will return a captcha challenge
 docker exec crowdsec cscli decisions remove --ip 10.0.0.10 -t captcha
 ```

@@ -684,16 +698,18 @@ The source code of the plugin should be organized as follows:
                    ├── LICENSE
                    ├── Makefile
                    ├── readme.md
-                    └── vendor/* 
+                    └── vendor/*
 ```

 For local development, a `docker-compose.local.yml` is provided which reproduces the directory layout needed by Traefik.  
-This works once you have generated and filled your *LAPI-KEY* (crowdsecLapiKey), if not read above for informations.
+This works once you have generated and filled your _LAPI-KEY_ (crowdsecLapiKey), if not read above for informations.

 ```bash
 docker compose -f docker-compose.local.yml up -d
 ```
+
 Equivalent to
+
 ```bash
 make run_local
 ```
@@ -701,7 +717,7 @@ make run_local
 ### About

 [mathieuHa](https://github.com/mathieuHa) and [I](https://github.com/maxlerebourg) have been using Traefik since 2020 at [Primadviz](https://primadviz.com).
-We come from a web development and security engineer background and wanted to add the power of a very promising technology (Crowdsec) to the edge router we love.  
+We come from a web development and security engineer background and wanted to add the power of a very promising technology (Crowdsec) to the edge router we love.

 We initially ran into this project: [github.com/fbonalair/traefik-crowdsec-bouncer](https://github.com/fbonalair/traefik-crowdsec-bouncer)
 It was using traefik and forward auth middleware to verify every request.  
--- a/bouncer.go
+++ b/bouncer.go
@@ -93,7 +93,7 @@ type Bouncer struct {

 // New creates the crowdsec bouncer plugin.
 func New(_ context.Context, next http.Handler, config *configuration.Config, name string) (http.Handler, error) {
-	log := logger.New(config.LogLevel)
+	log := logger.New(config.LogLevel, config.LogFilePath)
 	err := configuration.ValidateParams(config)
 	if err != nil {
 		log.Error("New:validateParams " + err.Error())
--- a/pkg/cache/cache_test.go
+++ b/pkg/cache/cache_test.go
@@ -11,7 +11,7 @@ import (
 func Test_Get(t *testing.T) {
 	IPInCache := "10.0.0.10"
 	IPNotInCache := "10.0.0.20"
-	client := &Client{cache: &localCache{}, log: logger.New("INFO")}
+	client := &Client{cache: &localCache{}, log: logger.New("INFO", "")}
 	client.Set(IPInCache, BannedValue, 10)
 	type args struct {
 		clientIP string
@@ -47,7 +47,7 @@ func Test_Get(t *testing.T) {
 }

 func Test_Set(t *testing.T) {
-	client := &Client{cache: &localCache{}, log: logger.New("INFO")}
+	client := &Client{cache: &localCache{}, log: logger.New("INFO", "")}
 	IPInCache := "10.0.0.11"
 	type args struct {
 		clientIP string
@@ -88,7 +88,7 @@ func Test_Set(t *testing.T) {
 func Test_Delete(t *testing.T) {
 	IPInCache := "10.0.0.12"
 	IPNotInCache := "10.0.0.22"
-	client := &Client{cache: &localCache{}, log: logger.New("INFO")}
+	client := &Client{cache: &localCache{}, log: logger.New("INFO", "")}
 	client.Set(IPInCache, BannedValue, 10)
 	type args struct {
 		clientIP string
--- a/pkg/configuration/configuration.go
+++ b/pkg/configuration/configuration.go
@@ -28,6 +28,9 @@ const (
 	AppsecMode        = "appsec"
 	HTTPS             = "https"
 	HTTP              = "http"
+	LogDEBUG          = "DEBUG"
+	LogINFO           = "INFO"
+	LogERROR          = "ERROR"
 	HcaptchaProvider  = "hcaptcha"
 	RecaptchaProvider = "recaptcha"
 	TurnstileProvider = "turnstile"
@@ -37,6 +40,7 @@ const (
 type Config struct {
 	Enabled                                  bool     `json:"enabled,omitempty"`
 	LogLevel                                 string   `json:"logLevel,omitempty"`
+	LogFilePath                              string   `json:"logFilePath,omitempty"`
 	CrowdsecMode                             string   `json:"crowdsecMode,omitempty"`
 	CrowdsecAppsecEnabled                    bool     `json:"crowdsecAppsecEnabled,omitempty"`
 	CrowdsecAppsecHost                       string   `json:"crowdsecAppsecHost,omitempty"`
@@ -98,7 +102,8 @@ func contains(source []string, target string) bool {
 func New() *Config {
 	return &Config{
 		Enabled:                        false,
-		LogLevel:                       "INFO",
+		LogLevel:                       LogINFO,
+		LogFilePath:                    "",
 		CrowdsecMode:                   LiveMode,
 		CrowdsecAppsecEnabled:          false,
 		CrowdsecAppsecHost:             "crowdsec:7422",
@@ -262,6 +267,17 @@ func ValidateParams(config *Config) error {
 		}
 	}

+	// Check logging configuration
+
+	if !contains([]string{LogERROR, LogDEBUG, LogINFO}, config.LogLevel) {
+		return fmt.Errorf("LogLevel should be one of (%s,%s,%s)", LogDEBUG, LogINFO, LogERROR)
+	}
+	if config.LogFilePath != "" {
+		_, err = os.OpenFile(filepath.Clean(config.LogFilePath), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
+		if err != nil {
+			return fmt.Errorf("LogFilePath is not writable %w", err)
+		}
+	}
 	return nil
 }

@@ -304,7 +320,7 @@ func validateParamsTLS(config *Config) error {

 func validateParamsIPs(listIP []string, key string) error {
 	if len(listIP) > 0 {
-		if _, err := ip.NewChecker(logger.New("INFO"), listIP); err != nil {
+		if _, err := ip.NewChecker(logger.New(LogINFO, ""), listIP); err != nil {
 			return fmt.Errorf("%s must be a list of IP/CIDR :%w", key, err)
 		}
 	}
--- a/pkg/configuration/configuration_test.go
+++ b/pkg/configuration/configuration_test.go
@@ -233,7 +233,7 @@ func Test_GetTLSConfigCrowdsec(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got, err := GetTLSConfigCrowdsec(tt.args.config, logger.New("INFO"))
+			got, err := GetTLSConfigCrowdsec(tt.args.config, logger.New("INFO", ""))
 			if (err != nil) != tt.wantErr {
 				t.Errorf("getTLSConfigCrowdsec() error = %v, wantErr %v", err, tt.wantErr)
 				return
--- a/pkg/logger/logger.go
+++ b/pkg/logger/logger.go
@@ -3,9 +3,11 @@
 package logger

 import (
+	"fmt"
 	"io"
 	"log"
 	"os"
+	"path/filepath"
 )

 // Log Logger struct.
@@ -16,15 +18,30 @@ type Log struct {
 }

 // New Set Default log level to info in case log level to defined.
-func New(logLevel string) *Log {
+func New(logLevel string, logFilePath string) *Log {
 	logError := log.New(io.Discard, "ERROR: CrowdsecBouncerTraefikPlugin: ", log.Ldate|log.Ltime)
 	logInfo := log.New(io.Discard, "INFO: CrowdsecBouncerTraefikPlugin: ", log.Ldate|log.Ltime)
 	logDebug := log.New(io.Discard, "DEBUG: CrowdsecBouncerTraefikPlugin: ", log.Ldate|log.Ltime)
+
 	logError.SetOutput(os.Stderr)
 	logInfo.SetOutput(os.Stdout)
+	// we initialize logger to STDOUT/STDERR first so if the file logger cannot be initialized we can inform the user
 	if logLevel == "DEBUG" {
 		logDebug.SetOutput(os.Stdout)
 	}
+	if logFilePath != "" {
+		logFile, err := os.OpenFile(filepath.Clean(logFilePath), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
+		if err != nil {
+			_ = fmt.Errorf("LogFilePath is not writable %w", err)
+		} else {
+			logInfo.SetOutput(logFile)
+			logError.SetOutput(logFile)
+			if logLevel == "DEBUG" {
+				logDebug.SetOutput(logFile)
+			}
+		}
+	}
+
 	return &Log{
 		logError: logError,
 		logInfo:  logInfo,