Add README.md with full documentation in Korean
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
kaffa
246
README.md
Normal file
246
README.md
Normal file
@@ -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 복원
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user