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 via SSH connection to remote servers.

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

# Build Podman/Docker image
podman build -t cf-bouncer-manager:latest .

# Run API server locally
uv run uvicorn api_server:app --host 0.0.0.0 --port 8000

Architecture

Runtime Environment:

• Python 3.13+ with uv as the package manager
• Connects to 2 remote servers via SSH:
  • Bouncer 서버: crowdsec-cloudflare-worker-bouncer가 실행되는 서버
  • CrowdSec 서버: CrowdSec 보안 엔진이 실행되는 서버
• Configuration stored at /etc/crowdsec/bouncers/crowdsec-cloudflare-worker-bouncer.yaml on the bouncer server

Key Components:

cf_bouncer.py (CLI):

• CLI Framework: Typer with Rich console output
• Remote Access: run_ssh() wrapper for SSH-based remote command execution with 60s timeout
• Config Management: YAML read/write via SSH, 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

api_server.py (REST API):

• Framework: FastAPI with automatic OpenAPI/Swagger documentation
• Endpoints: RESTful API for all CLI operations
• Docs: Swagger UI available at /docs

Data Flow:

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

SSH 환경변수 설정

프로그램 실행 전 아래 환경변수를 설정해야 합니다:

# Bouncer 서버 (필수)
export CFB_BOUNCER_HOST="hostname"           # SSH 호스트 (예: 192.168.1.10 또는 user@host)
export CFB_BOUNCER_PORT="22"                 # SSH 포트 (기본값: 22)
export CFB_BOUNCER_USER="root"               # SSH 사용자 (기본값: root)
export CFB_BOUNCER_KEY="/path/to/key"        # SSH 키 경로 (선택)

# CrowdSec 서버 (필수)
export CFB_CROWDSEC_HOST="hostname"          # SSH 호스트
export CFB_CROWDSEC_PORT="22"                # SSH 포트 (기본값: 22)
export CFB_CROWDSEC_USER="root"              # SSH 사용자 (기본값: root)
export CFB_CROWDSEC_KEY="/path/to/key"       # SSH 키 경로 (선택)

서버 요구사항

각 서버에 sshd가 설치 및 실행되어야 합니다:

# Debian/Ubuntu
apt install openssh-server
systemctl enable --now ssh

# SSH 키 기반 인증 설정 (권장)
ssh-copy-id user@bouncer-server
ssh-copy-id user@crowdsec-server

Container 실행

# Podman/Docker 이미지 빌드
podman build -t cf-bouncer-manager:latest .

# CLI 모드
podman run --rm \
  -v ~/.ssh:/root/.ssh:ro \
  -e CFB_BOUNCER_HOST="10.253.100.131" \
  -e CFB_CROWDSEC_HOST="10.253.100.240" \
  cf-bouncer-manager:latest [command]

# API 서버 모드
podman run -d --rm --name cfb-api \
  --network host \
  -v ~/.ssh:/root/.ssh:ro \
  -e CFB_BOUNCER_HOST="10.253.100.131" \
  -e CFB_CROWDSEC_HOST="10.253.100.240" \
  --entrypoint uv \
  cf-bouncer-manager:latest \
  run uvicorn api_server:app --host 0.0.0.0 --port 8000

CLI Commands

명령어	설명
list	보호 중인 도메인 목록 표시
show <domain>	특정 도메인 상세 정보
add <domain>	새 도메인 추가
edit <domain>	기존 도메인 설정 수정
remove <domain>	도메인 제거
sync	Cloudflare의 모든 도메인을 보호 목록에 추가
apply	설정 적용 (bouncer 서비스 재시작)
status	bouncer 상태 확인
available	Cloudflare에서 추가 가능한 도메인 목록
logs [-f]	bouncer 로그 조회 (실시간 추적 옵션)
decisions	CrowdSec 현재 차단 결정 조회
metrics	bouncer Prometheus 메트릭 조회
backup	현재 설정 백업
restore [file]	백업에서 설정 복원
diff [file]	현재 설정과 백업 비교
export	설정을 파일로 내보내기
history	변경 이력 조회

Dependencies

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

External Requirements

• SSH access to bouncer and CrowdSec servers
• Cloudflare API token configured in bouncer YAML
• Access to /etc/crowdsec/bouncers/ directory on bouncer server