6a26c0c4e4
- Add FastAPI-based REST API server (api_server.py) - Add Dockerfile and docker-compose.yaml for containerized deployment - Add Gitea Actions CI workflow for building and pushing images - Refactor CLI to support dual-server SSH (bouncer + crowdsec) - Update dependencies with FastAPI and uvicorn - Update CLAUDE.md and README.md with full documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
# 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
|