eBPF-hid_guard

eBPF-hid_guard

아래 이 저장소가 보관된 이유를 참조하세요.

Linux 커널 공간 보안 모니터로, eBPF HID-BPF struct_ops를 사용하여 HID 인젝션 공격(Rubber Ducky, O.MG Cable, ESP32 기반 키보드 에뮬레이터)을 탐지하고 차단합니다.

이 도구가 하는 일

악성 HID 장치는 키보드를 에뮬레이트하여 사람이 입력하는 속도보다 훨씬 빠르게 키 입력을 주입합니다. 이 도구는 이러한 타이밍 이상을 감지하여 공격이 완료되기 전에 해당 장치를 커널 HID 드라이버에서 바인딩 해제합니다.

시작 시 이 도구는 현재 연결된 모든 HID 장치의 스냅샷을 찍고 이를 무시합니다. 새로 연결된 장치만 모니터링됩니다. USB 및 Bluetooth HID 장치를 모두 지원합니다.

브랜치 구조

main — 작동하는 개념 증명

ESP32 기반 키보드 에뮬레이터로 테스트된 기능적 종단간 파이프라인:

• 시작 시 기존 장치를 스냅샷하고 무시
• 병렬 USB 및 BLE 탐지 스레드 — 새 장치를 먼저 탐지하는 쪽이 승리
• 발견된 장치에 HID-BPF struct_ops 프로그램 연결
• BPF 측에서 링 버퍼를 통해 원시 HID 리포트 바이트, 타임스탬프, 공급업체/제품/버스 캡처
• 사용자 공간에서 키 입력 간 델타를 계산하고 의심 카운터를 추적하며 임계값을 초과하면 sysfs를 통해 장치 바인딩 해제

재작성을 유발한 알려진 제한 사항:

• 리포트 크기가 8 또는 9바이트로 하드코딩됨(표준 부트 프로토콜 키보드만 해당) — 비표준 디스크립터에서 깨짐
• HID 리포트 디스크립터 파싱 없음 — 장치 유형이 가정되며 확인되지 않음; 마우스, 터치패드 또는 복합 장치에서 오작동
• 탐지 로직이 전적으로 사용자 공간에 있음 — BPF는 원시 데이터 파이프로만 사용됨
• hid_id가 sysfs 마이너 번호에서 파생되며 재부팅 간에 안정적이지 않음

v0.1 — 클린 재작성 (중단됨)

BPF 레이어를 재연결하기 전에 구축된 이식 가능한 기반:

• /sys/bus/hid/devices/를 통해 모든 HID 장치 열거
• sysfs에서 원시 리포트 디스크립터를 읽고 16진수 덤프
• HID 리포트 디스크립터 파서 진행 중 (hid_desc_parse.c) — 장치 유형 식별 완료되지 않음
• 메모리 클린 (AddressSanitizer로 확인됨)

이 저장소가 보관된 이유

두 브랜치 모두 동일한 한계에 부딪혔습니다: HID-BPF는 원시 바이트 배열로 작동하므로 탐지 로직이 어떻게 분할되든 모든 디스크립터 파싱과 장치 유형 확인이 사용자 공간에 있어야 합니다. 이 스캐폴딩을 처음부터 계속 구축하는 대신 [udev-hid-bpf]로 이전했습니다.

이 도구가 하는 일

악성 HID 장치는 키보드를 에뮬레이트하여 사람이 입력하는 속도보다 훨씬 빠르게 키 입력을 주입합니다. 이 도구는 이러한 타이밍 이상을 감지하여 공격이 완료되기 전에 해당 장치를 커널 HID 드라이버에서 바인딩 해제합니다.

시작 시 이 도구는 현재 연결된 모든 HID 장치의 스냅샷을 찍고 이를 무시합니다. 새로 연결된 장치만 모니터링됩니다. USB 및 Bluetooth HID 장치를 모두 지원합니다.

브랜치 구조

main — 작동하는 개념 증명

ESP32 기반 키보드 에뮬레이터로 테스트된 기능적 종단간 파이프라인:

• 시작 시 기존 장치를 스냅샷하고 무시
• 병렬 USB 및 BLE 탐지 스레드 — 새 장치를 먼저 탐지하는 쪽이 승리
• 발견된 장치에 HID-BPF struct_ops 프로그램 연결
• BPF 측에서 링 버퍼를 통해 원시 HID 리포트 바이트, 타임스탬프, 공급업체/제품/버스 캡처
• 사용자 공간에서 키 입력 간 델타를 계산하고 의심 카운터를 추적하며 임계값을 초과하면 sysfs를 통해 장치 바인딩 해제

재작성을 유발한 알려진 제한 사항:

• 리포트 크기가 8 또는 9바이트로 하드코딩됨(표준 부트 프로토콜 키보드만 해당) — 비표준 디스크립터에서 깨짐
• HID 리포트 디스크립터 파싱 없음 — 장치 유형이 가정되며 확인되지 않음; 마우스, 터치패드 또는 복합 장치에서 오작동
• 탐지 로직이 전적으로 사용자 공간에 있음 — BPF는 원시 데이터 파이프로만 사용됨
• hid_id가 sysfs 마이너 번호에서 파생되며 재부팅 간에 안정적이지 않음

v0.1 — 클린 재작성 (활성 개발)

BPF 레이어를 재연결하기 전에 구축 중인 이식 가능한 기반:

• /sys/bus/hid/devices/를 통해 모든 HID 장치 열거
• sysfs에서 원시 리포트 디스크립터를 읽고 16진수 덤프
• HID 리포트 디스크립터 파서 진행 중 (hid_desc_parse.c) — 연결 전에 장치 유형 식별 예정
• 메모리 클린 (AddressSanitizer로 확인됨)

의도된 아키텍처

┌─────────────────────────────────────────────────────┐
│                    Userspace                         │
│                                                      │
│  udev monitor → descriptor parse → keyboard?         │
│       ↓                                              │
│  populate BPF config maps (thresholds, device info)  │
│       ↓                                              │
│  attach HID-BPF struct_ops to hid_id                 │
│       ↓                                              │
│  ring buffer consumer → sysfs unbind on attack       │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  BPF (kernel side)                   │
│                                                      │
│  hid_device_event → timing math (Welford's online    │
│  variance, fixed-point) → per-key timestamp maps     │
│  → ring buffer submit on anomaly                     │
└─────────────────────────────────────────────────────┘

탐지 로직이 BPF로 이동합니다. 사용자 공간은 디스크립터 파싱, 설정 맵 채우기, 바인딩 해제 응답을 처리합니다. 장치 연결과 BPF 연결 사이의 열거 창은 문서화된 제한된 한계입니다 — 실제 HID 인젝션 도구는 이 창 내에 속하는 의도적인 사후 열거 지연을 포함합니다.

요구 사항

• Linux 커널 ≥ 6.3 (HID-BPF struct_ops 안정화)
• libbpf 개발 헤더
• LLVM/Clang (BPF 컴파일용)
• libelf 및 zlib 개발 헤더
• 루트 권한

빌드

make

사용법

# 자동 탐지: 메시지가 표시되면 장치를 연결하거나 페어링하세요
sudo ./hid_guard

# 알려진 hid_id로 수동 재정의
sudo ./hid_guard <hid_id>

# 사용 가능한 HID 장치 목록 보기
ls /sys/bus/hid/devices/

탐지 조정 변수 (main.c)

상태

테스트

ESP32-S2가 BLE 키 입력 전송에 사용되었습니다. 다음으로, USB 포트를 대상으로 rubber ducky 또는 ESP32-S3와 같은 하드웨어로 테스트

라이선스

GPL v2