cf-bouncer-manager/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

CrowdSec Cloudflare Bouncer Manager (cf-bouncer-manager) is a Korean-language CLI tool for managing the CrowdSec Cloudflare Worker Bouncer. It manages protected domains, Turnstile CAPTCHA settings, and bouncer configuration through Incus/LXD containers.

Development Commands

# Run the CLI (via uv package manager)
uv run python cf_bouncer.py [command] [options]

# Or use the wrapper script
./cfb [command] [options]

# Install dependencies
uv sync

Architecture

Runtime Environment:

• Python 3.13+ with uv as the package manager
• Interacts with Incus/LXD containers: cs-cf-worker-bouncer (bouncer service) and crowdsec (security engine)
• Configuration stored at /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml inside the container

Key Components in cf_bouncer.py:

• CLI Framework: Typer with Rich console output
• Container Interaction: run_incus() wrapper for all container commands with 60s timeout
• Config Management: YAML read/write via Incus exec, automatic backup before writes (keeps 20)
• Cloudflare API: Domain/zone queries with pagination support, 30s request timeout
• Audit Logging: All actions logged to ~/cf-bouncer-manager/history.log

Data Flow:

1. CLI command → Read config from container via Incus
2. Modify config in memory
3. Backup existing config → Write new config → Optionally restart service via do_apply()

CLI Commands

list, show, add, edit, remove - Domain CRUD operations sync - Bulk import all Cloudflare zones apply - Restart bouncer service to apply changes status - Check bouncer process and CrowdSec status available - List unprotected Cloudflare domains logs [-f] - View bouncer logs (with optional follow) decisions, metrics - CrowdSec data queries backup, restore, diff - Configuration backup management export - Export domain list to YAML/JSON history - View action history

Dependencies

Core: typer, pyyaml, requests, rich (see pyproject.toml)

External Requirements

• Incus/LXD with containers: cs-cf-worker-bouncer, crowdsec
• Cloudflare API token configured in bouncer YAML
• Access to /etc/crowdsec/bouncers/ directory