diff --git a/README.md b/README.md new file mode 100644 index 0000000..35d4862 --- /dev/null +++ b/README.md @@ -0,0 +1,246 @@ +# XDP Defense + +XDP Blocker + DDoS Defense 통합 시스템. libxdp 디스패처를 사용해 두 XDP 프로그램을 하나의 인터페이스에서 체인 실행합니다. + +## 아키텍처 + +``` +패킷 → [xdp_dispatcher] + → xdp_blocker (우선순위 10): + 화이트리스트 → PASS + 블록리스트 → DROP + 그 외 → PASS + → xdp_ddos (우선순위 20): + 화이트리스트 → PASS (속도제한 우회) + 차단 IP → DROP + 속도 초과 → DROP + 그 외 → PASS → 커널 스택 +``` + +- **xdp_blocker**: CIDR/국가/화이트리스트 기반 패킷 필터링 (LPM Trie) +- **xdp_ddos**: Per-IP 속도 제한, 자동 차단(만료 지원), AI 트래픽 피처 수집 +- **화이트리스트 공유**: `LIBBPF_PIN_BY_NAME`으로 `/sys/fs/bpf/xdp-defense/`에 핀닝하여 두 프로그램이 동일한 맵 참조 +- **데몬**: EWMA 이상 탐지, Isolation Forest AI, 시간대별 프로필 전환, 만료 블록 자동 정리 + +## 요구사항 + +- Linux 커널 6.x+ +- clang, libbpf, libxdp (xdp-loader) +- bpftool, iproute2 +- Python 3, PyYAML +- scikit-learn (AI 탐지 사용 시) + +## 설치 + +```bash +cd /opt/xdp-defense +make check-deps # 의존성 확인 +make build # BPF 프로그램 컴파일 +make install # CLI, 라이브러리, systemd 서비스 설치 +make enable # 부팅 시 자동 시작 +``` + +## 빠른 시작 + +```bash +# 서비스 시작 (XDP 로드 + 데몬) +systemctl enable --now xdp-defense + +# 상태 확인 +xdp-defense status +``` + +## CLI 사용법 + +### 시스템 + +```bash +xdp-defense load [iface] # XDP 프로그램 로드 (기본: config의 interface) +xdp-defense unload [iface] # XDP 프로그램 언로드 +xdp-defense status # 전체 상태 확인 +xdp-defense build # BPF 프로그램 재빌드 +xdp-defense stop-all # 데몬 중지 + XDP 언로드 +``` + +### CIDR 차단 (blocker) + +```bash +xdp-defense blocker add 1.2.3.0/24 # CIDR 차단 +xdp-defense blocker add 1.2.3.4 # 단일 IP 차단 +xdp-defense blocker add 2001:db8::/32 # IPv6 차단 +xdp-defense blocker del 1.2.3.0/24 # 차단 해제 +xdp-defense blocker list # 차단 목록 +xdp-defense blocker stats # 통계 (passed/dropped/whitelisted) +xdp-defense blocker enable # 필터링 활성화 +xdp-defense blocker disable # 필터링 비활성화 +``` + +### 국가 차단 + +```bash +xdp-defense country add br # 브라질 차단 (IPv4+IPv6, ipdeny.com에서 다운로드) +xdp-defense country add cn # 중국 차단 +xdp-defense country del br # 브라질 차단 해제 +xdp-defense country list # 차단 국가 목록 +``` + +### 화이트리스트 + +```bash +# 프리셋 (자동 다운로드) +xdp-defense whitelist add cloudflare # Cloudflare CDN +xdp-defense whitelist add aws # Amazon Web Services +xdp-defense whitelist add google # Google Cloud +xdp-defense whitelist add github # GitHub + +# 직접 IP/CIDR +xdp-defense whitelist add 8.8.8.8/32 # 단일 IP +xdp-defense whitelist add 10.0.0.0/8 # CIDR 대역 + +xdp-defense whitelist del cloudflare # 프리셋 제거 +xdp-defense whitelist del 8.8.8.8/32 # IP 제거 +xdp-defense whitelist list # 목록 +``` + +화이트리스트 IP는 blocker의 블록리스트를 우회하고, ddos의 속도 제한도 우회합니다. + +### DDoS 방어 + +```bash +xdp-defense ddos stats # 통계 (passed/dropped/total) +xdp-defense ddos top [N] # 패킷 수 기준 상위 N개 IP +xdp-defense ddos blocked # 차단 IP 목록 (만료 시간 포함) +xdp-defense ddos block 1.2.3.4 3600 # 1시간 차단 +xdp-defense ddos block 1.2.3.4 0 # 영구 차단 +xdp-defense ddos unblock 1.2.3.4 # 차단 해제 +xdp-defense ddos config show # 속도 제한 설정 확인 +xdp-defense ddos config set pps 500 # PPS 임계값 변경 +xdp-defense ddos config set bps 1000000 # BPS 임계값 변경 +xdp-defense ddos config set window 1 # 윈도우 (초) +``` + +### AI 이상 탐지 + +```bash +xdp-defense ai status # AI 모델 상태 +xdp-defense ai retrain # 모델 재학습 요청 (SIGUSR1) +``` + +### 데몬 + +```bash +xdp-defense daemon start # 백그라운드 시작 +xdp-defense daemon stop # 중지 +xdp-defense daemon restart # 재시작 +``` + +### GeoIP 조회 + +```bash +xdp-defense geoip 1.2.3.4 # 국가, 도시, ASN, 차단 상태 확인 +``` + +### 하위 호환 + +`xdp-block` 명령은 `xdp-defense blocker`로 자동 매핑됩니다: + +```bash +xdp-block add 1.2.3.0/24 # = xdp-defense blocker add 1.2.3.0/24 +xdp-block stats # = xdp-defense blocker stats +xdp-block country-add br # = xdp-defense country add br +``` + +## 설정 + +`/etc/xdp-defense/config.yaml`: + +```yaml +general: + interface: eth0 # XDP 인터페이스 + log_level: info + +blocker: + enabled: true + config_dir: /etc/xdp-blocker # 블록리스트/국가/화이트리스트 데이터 + +rate_limits: + default_pps: 1000 # 초당 패킷 임계값 + default_bps: 0 # 초당 바이트 (0=비활성) + window_sec: 1 + profiles: # 시간대별 프로필 + business_hours: + hours: "09:00-18:00" + weekdays: "mon-fri" + pps: 2000 + night: + hours: "00:00-06:00" + pps: 500 + +escalation: + temp_block_after: 5 # 위반 N회 후 임시 차단 + temp_block_duration: 300 # 임시 차단 시간 (초) + violation_window: 600 # 위반 기억 윈도우 (초) + +ewma: + alpha: 0.3 # EWMA 평활 계수 + threshold_multiplier: 3.0 # 기준선 대비 이상 판단 배율 + +ai: + enabled: true + model_type: IsolationForest + learning_duration: 86400 # 학습 기간 (초) + anomaly_threshold: -0.16 +``` + +## 디렉토리 구조 + +``` +/opt/xdp-defense/ # 프로젝트 루트 +├── bpf/ # BPF 소스 및 오브젝트 +│ ├── xdp_blocker.c +│ └── xdp_ddos.c +├── lib/ # Python 라이브러리 +│ ├── xdp_common.py +│ ├── xdp_country.py +│ ├── xdp_whitelist.py +│ └── xdp_defense_daemon.py +├── bin/ # 실행 스크립트 +│ ├── xdp-defense +│ └── xdp-startup.sh +├── config/ # 설정 템플릿 +│ ├── config.yaml +│ └── xdp-defense.service +└── Makefile + +/etc/xdp-defense/config.yaml # 런타임 설정 +/etc/xdp-blocker/ # 블록리스트/국가/화이트리스트 데이터 +/var/lib/xdp-defense/ # PID, AI 모델, 학습 데이터 +/sys/fs/bpf/xdp-defense/ # 공유 BPF 맵 핀 경로 +``` + +## systemd 서비스 + +```bash +systemctl enable --now xdp-defense # 활성화 + 시작 +systemctl restart xdp-defense # 재시작 +systemctl status xdp-defense # 상태 +journalctl -u xdp-defense -f # 로그 +``` + +서비스 흐름: +1. `ExecStartPre`: XDP 프로그램 로드 + 블록리스트/국가/화이트리스트 복원 +2. `ExecStart`: 데몬 포그라운드 실행 (EWMA, AI, 프로필, 클린업 스레드) +3. `ExecStop`: 데몬 중지 + XDP 언로드 + +## 제거 + +```bash +make uninstall # CLI, 서비스 제거 (설정은 보존) +systemctl stop xdp-defense # 서비스 중지 +``` + +롤백 (이전 시스템으로): +```bash +systemctl stop xdp-defense +systemctl start xdp-blocker # 기존 blocker 복원 +```