xdp-defense/README.md

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 탐지 사용 시)

설치

cd /opt/xdp-defense
make check-deps    # 의존성 확인
make build         # BPF 프로그램 컴파일
make install       # CLI, 라이브러리, systemd 서비스 설치
make enable        # 부팅 시 자동 시작

빠른 시작

# 서비스 시작 (XDP 로드 + 데몬)
systemctl enable --now xdp-defense

# 상태 확인
xdp-defense status

CLI 사용법

시스템

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)

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              # 필터링 비활성화

국가 차단

xdp-defense country add br     # 브라질 차단 (IPv4+IPv6, ipdeny.com에서 다운로드)
xdp-defense country add cn     # 중국 차단
xdp-defense country del br     # 브라질 차단 해제
xdp-defense country list       # 차단 국가 목록

화이트리스트

# 프리셋 (자동 다운로드)
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 방어

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 이상 탐지

xdp-defense ai status     # AI 모델 상태
xdp-defense ai retrain    # 모델 재학습 요청 (SIGUSR1)
xdp-defense ai traffic    # 시간대별 트래픽 요약 (최근 24시간)
xdp-defense ai log [N]    # 최근 N개 트래픽 로그 (기본 20)

• 시간대별 모델: night(0-6시), morning(6-12시), afternoon(12-18시), evening(18-24시) 4개 IsolationForest
• 자동 재학습: retrain_interval(기본 24시간) 마다 최근 retrain_window(기본 7일) 데이터로 백그라운드 재학습
• 트래픽 로깅: 5초 간격으로 17개 피처를 SQLite에 기록 (/var/lib/xdp-defense/traffic_log.db)
• 공격 샘플 필터링: 재학습 시 이상치(score < -0.5) 자동 제외

데몬

xdp-defense daemon start     # 백그라운드 시작
xdp-defense daemon stop      # 중지
xdp-defense daemon restart   # 재시작

GeoIP 조회

xdp-defense geoip 1.2.3.4   # 국가, 도시, ASN, 차단 상태 확인

하위 호환

xdp-block 명령은 xdp-defense blocker로 자동 매핑됩니다:

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:

general:
  interface: eth0              # XDP 인터페이스
  log_level: info

blocker:
  enabled: true
  config_dir: /etc/xdp-defense  # 블록리스트/국가/화이트리스트 데이터

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
  traffic_log_db: /var/lib/xdp-defense/traffic_log.db
  traffic_log_retention_days: 7
  retrain_interval: 86400      # 자동 재학습 주기 (초)
  retrain_window: 604800       # 학습 데이터 범위 (최근 7일)

디렉토리 구조

/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-defense/              # 블록리스트/국가/화이트리스트 데이터
/var/lib/xdp-defense/          # PID, AI 모델, 학습 데이터
/sys/fs/bpf/xdp-defense/       # 공유 BPF 맵 핀 경로

systemd 서비스

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 언로드

제거

make uninstall                       # CLI, 서비스 제거 (설정은 보존)
systemctl stop xdp-defense           # 서비스 중지

롤백 (이전 시스템으로):

systemctl stop xdp-defense
systemctl start xdp-blocker          # 기존 blocker 복원

로드맵

• 웹훅 알림: 공격 탐지/자동 차단 시 외부 알림 발송 (Slack, Discord, 일반 webhook)
  • 설정 예시: notifications: { webhook_url: "https://...", events: [attack_detected, ip_blocked] }
  • AI 이상 탐지, EWMA 위반, 자동 차단 이벤트에 대해 HTTP POST 알림