docs(crowdsec): fix documentation to match actual configuration

[EsOsO]

Summary

Comprehensive review and correction of CrowdSec documentation to accurately reflect the actual implementation, including AppSec WAF, CTI integration, Telegram notifications, and Docker label-based log parsing.

Key Corrections

❌ What Was Wrong → ✅ What's Correct

Configuration Location

• ❌ Separate compose/crowdsec/compose.yaml
• ✅ In compose/core/traefik/compose.yaml alongside Traefik

Collections

• ❌ Only crowdsecurity/traefik and crowdsecurity/http-cve
• ✅ 6 pre-installed collections including AppSec WAF:
  • crowdsecurity/appsec-generic-rules
  • crowdsecurity/appsec-virtual-patching
  • Dominic-Wagner/vaultwarden
  • LePresidente/authelia
  • openappsec/openappsec

Data Sources

• ❌ File-based log parsing (/var/log/traefik)
• ✅ Docker container labels (use_container_labels: true)
• ✅ AppSec WAF on port 7422

Bouncer Configuration

• ❌ Simple configuration with only API host and key
• ✅ Complete configuration with:
  • AppSec WAF integration (crowdsecappsechost)
  • Redis cache (traefik-redict:6379)
  • Client trusted IPs
  • Forwarded headers trusted IPs

Network & Docker Access

• ❌ Direct Docker socket access
• ✅ Via Cetusguard proxy: tcp://cetusguard:2375
• ✅ Networks: vnet-traefik, vnet-socket

Whitelist

• ❌ Path: compose/crowdsec/config/parsers/s02-enrich/whitelist.yaml
• ✅ Path: compose/core/traefik/crowdsec/ip-whitelist.yaml
• ✅ RFC 1918 private networks whitelisted by default

New Documentation Sections

1. Cyber Threat Intelligence (CTI)

CTI API Integration:

• Background noise score-based ban duration
• False positive detection
• Threat classifications
• Attack history

Custom Profiles:

# Ban duration: 4h + 2h per background noise score point
duration_expr: "Sprintf('%dm', (240 + (120 * CrowdsecCTI(...).GetBackgroundNoiseScore())))"

Progressive bans based on repeat offenses:

# 12h, 24h, 36h, 48h, etc.
duration_expr: "Sprintf('%dh', (GetDecisionsCount(...) + 1) * 12)"

2. Application Security (AppSec) WAF

Virtual Patching:

• SQL Injection
• XSS (Cross-Site Scripting)
• Path Traversal
• Command Injection
• SSRF
• Known CVEs (Log4Shell, Spring4Shell, ProxyShell, etc.)

Configuration:

listen_addr: 0.0.0.0:7422
appsec_config: crowdsecurity/virtual-patching

3. Telegram Notifications

Alert Format:

• Banned IP address
• Action type and duration
• Triggering scenario
• CTI scores (overall, last day, week, month)
• Threat classifications
• Links to Shodan and CrowdSec CTI

Setup Requirements:

• TELEGRAM_BOT_ID (bot token)
• TELEGRAM_CHAT_ID (chat ID)

4. Data Sources

Docker Container Labels:

source: docker
use_container_labels: true
check_interval: 10s

Containers must be labeled:

labels:
  crowdsec.enable: true
  crowdsec.labels.type: traefik

5. Required Secrets

Documented all required Infisical secrets:

• TRAEFIK_CROWDSEC_BOUNCER - Bouncer API key
• CROWDSEC_CTI_API_KEY - CTI API key
• TELEGRAM_BOT_ID - Telegram bot token
• TELEGRAM_CHAT_ID - Telegram chat ID

Updates by Section

Configuration

• ✅ Corrected file paths
• ✅ Added complete environment variables
• ✅ Documented networks (vnet-traefik, vnet-socket)
• ✅ Added volumes configuration
• ✅ Documented Cetusguard integration

Collections

• ✅ Listed all pre-installed collections
• ✅ Separated pre-installed vs additional recommended

Data Sources

• ✅ New section on Docker label parsing
• ✅ Documented AppSec WAF component
• ✅ Container labeling requirements

Traefik Bouncer

• ✅ Complete configuration with all parameters
• ✅ AppSec WAF integration
• ✅ Redis cache configuration
• ✅ Trusted IPs setup

CTI

• ✅ Complete new section
• ✅ CTI API configuration
• ✅ Background noise score profiles
• ✅ Progressive ban formulas

Notifications

• ✅ New Telegram notifications section
• ✅ Alert format details
• ✅ Setup instructions

AppSec WAF

• ✅ Complete new section
• ✅ Virtual patching explained
• ✅ Protected attack types
• ✅ Metrics commands

Whitelists

• ✅ Corrected file path
• ✅ Documented RFC 1918 default whitelist
• ✅ Fixed YAML structure

Troubleshooting

• ✅ Removed file log verification
• ✅ Added Cetusguard connectivity checks
• ✅ Added container label verification
• ✅ Added AppSec WAF testing examples
• ✅ Added acquisition sources check

Best Practices

• ✅ Added Redis cache monitoring
• ✅ Added CTI score review
• ✅ Added AppSec monitoring
• ✅ Documented required secrets
• ✅ Updated backup paths

Verification

All changes verified against actual configuration in:

• ✅ compose/core/traefik/compose.yaml
• ✅ compose/core/traefik/crowdsec/config.yaml
• ✅ compose/core/traefik/crowdsec/acquis.d/*.yaml
• ✅ compose/core/traefik/crowdsec/profiles.yaml
• ✅ compose/core/traefik/crowdsec/telegram.yaml
• ✅ compose/core/traefik/crowdsec/ip-whitelist.yaml
• ✅ compose/core/traefik/rules/crowdsec.yml

Impact

• 📚 Documentation now accurately reflects complex implementation
• 🛡️ AppSec WAF features properly documented
• 🔍 CTI integration explained
• 📱 Telegram notifications setup guide
• 🔧 Troubleshooting steps will work correctly
• 🎯 Users understand Docker label-based log parsing

Type of Change

• Documentation correction (critical accuracy fixes)
• No code changes

🤖 Generated with Claude Code

[github-actions]

📚 Documentation Build Report

✅ Documentation built successfully!

Site size: 6.1M

Preview: Documentation will be deployed to GitHub Pages after merging to main.
Current site: https://esoso.github.io/Omakase/

Build details

• Workflow run: 19759106663
• Commit: be7d638
• Python version: 3.11
• MkDocs Material theme: Latest