cf-bouncer-manager/README.md

CrowdSec Cloudflare Bouncer Manager

CrowdSec Cloudflare Worker Bouncer를 관리하는 CLI/API 도구입니다.

기능

• 보호 도메인 CRUD (추가/조회/수정/삭제)
• Cloudflare 도메인 자동 동기화
• Turnstile CAPTCHA 설정 관리
• CrowdSec 차단 결정 조회
• 설정 백업/복원
• REST API 서버 모드 지원

요구사항

• Python 3.13+
• SSH 접근 가능한 2개의 서버:
  • Bouncer 서버 (crowdsec-cloudflare-worker-bouncer 실행)
  • CrowdSec 서버 (CrowdSec 엔진 실행)

설치

로컬 실행

# uv 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 의존성 설치
uv sync

# 환경변수 설정
export CFB_BOUNCER_HOST="10.253.100.131"
export CFB_CROWDSEC_HOST="10.253.100.240"

# CLI 실행
uv run python cf_bouncer.py list

# API 서버 실행
uv run uvicorn api_server:app --host 0.0.0.0 --port 8000

Container 실행 (권장)

# 이미지 빌드
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 list

# 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

Alias 설정 (편의용)

# ~/.bashrc 또는 ~/.zshrc에 추가
alias cfb='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'

# 사용
cfb list
cfb status
cfb add example.com

환경변수

변수	필수	기본값	설명
CFB_BOUNCER_HOST	O	-	Bouncer 서버 호스트
CFB_BOUNCER_PORT	X	22	Bouncer 서버 SSH 포트
CFB_BOUNCER_USER	X	root	Bouncer 서버 SSH 사용자
CFB_BOUNCER_KEY	X	-	Bouncer 서버 SSH 키 경로
CFB_CROWDSEC_HOST	O	-	CrowdSec 서버 호스트
CFB_CROWDSEC_PORT	X	22	CrowdSec 서버 SSH 포트
CFB_CROWDSEC_USER	X	root	CrowdSec 서버 SSH 사용자
CFB_CROWDSEC_KEY	X	-	CrowdSec 서버 SSH 키 경로
CFB_API_HOST	X	0.0.0.0	API 서버 바인드 호스트
CFB_API_PORT	X	8000	API 서버 포트

CLI 명령어

cfb list                    # 보호 중인 도메인 목록
cfb show <domain>           # 도메인 상세 정보
cfb add <domain>            # 새 도메인 추가
cfb edit <domain>           # 도메인 설정 수정
cfb remove <domain>         # 도메인 제거
cfb sync                    # Cloudflare 도메인 동기화
cfb apply                   # 설정 적용 (서비스 재시작)
cfb status                  # bouncer 상태 확인
cfb available               # 추가 가능한 도메인 목록
cfb logs [-f]               # 로그 조회 (-f: 실시간)
cfb decisions               # CrowdSec 차단 결정 조회
cfb metrics                 # Prometheus 메트릭 조회
cfb backup                  # 설정 백업
cfb restore [file]          # 설정 복원
cfb diff [file]             # 설정 비교
cfb export                  # 설정 내보내기
cfb history                 # 변경 이력 조회

REST API

API 서버 실행 후 http://localhost:8000/docs에서 Swagger UI를 확인할 수 있습니다.

주요 엔드포인트

Method	Endpoint	설명
GET	/health	헬스 체크
GET	/domains	보호 중인 도메인 목록
GET	/domains/{domain}	도메인 상세 정보
POST	/domains	새 도메인 추가
PUT	/domains/{domain}	도메인 설정 수정
DELETE	/domains/{domain}	도메인 제거
POST	/apply	설정 적용
GET	/status	bouncer 상태 확인
GET	/available	추가 가능한 도메인 목록
GET	/decisions	CrowdSec 차단 결정 조회
POST	/sync	Cloudflare 도메인 동기화
POST	/backup	설정 백업
GET	/history	변경 이력 조회

API 사용 예시

# 도메인 목록 조회
curl http://localhost:8000/domains

# 도메인 추가
curl -X POST http://localhost:8000/domains \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "action": "captcha", "turnstile_enabled": true}'

# 도메인 수정
curl -X PUT http://localhost:8000/domains/example.com \
  -H "Content-Type: application/json" \
  -d '{"action": "ban"}'

# 설정 적용
curl -X POST http://localhost:8000/apply

# 상태 확인
curl http://localhost:8000/status

서버 설정

각 서버에 sshd가 설치되어 있어야 합니다:

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

# SSH 키 복사
ssh-copy-id root@bouncer-server
ssh-copy-id root@crowdsec-server

라이선스

MIT