# 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

```bash
# 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 환경변수 설정

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

```bash
# 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가 설치 및 실행되어야 합니다:

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

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

## Container 실행

```bash
# 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