휴대폰에서 실행되는 로컬 AI 기반 레드팀 도구
# Nightcrawler
스마트폰에서 완전히 실행되는 자율 침투 테스트 에이전트입니다. 네트워크에 폰을 놓아두고 떠나면, 호스트를 발견하고 서비스를 매핑하며 취약점을 찾고 침투 테스트 보고서를 생성합니다 — 클라우드 연결 없이 말이죠.
```
░█▄░█ █ █▀▀ █░█ ▀█▀ █▀▀ █▀█ ▄▀█ █░█░█ █░░ █▀▀ █▀█
░█░▀█ █ █▄█ █▀█ ░█░ █▄▄ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ██▄ █▀▄ v0.1.0
AUTONOMOUS MOBILE PENTEST AGENT
OnePlus 8 · NetHunter · LFM2.5-1.2B · OpenCL GPU
```
## 이게 뭔가요?
**침투 테스트(Pentesting)** 는 네트워크 소유자의 명시적 허가를 받아 공격을 시뮬레이션하여 컴퓨터 네트워크의 보안을 테스트하는 관행입니다. 전문 침투 테스터는 실제 공격자가 발견하기 *전에* 취약점을 찾기 위해 고용됩니다.
Nightcrawler는 이 과정을 휴대폰에서 자동화합니다. 휴대폰 GPU에서 로컬로 실행되는 소형 AI 모델(LFM2.5-1.2B-Instruct-Heretic, 12억 파라미터)을 사용하여 다음에 무엇을 할지 — 어떤 호스트를 탐색할지, 어떤 도구를 사용할지, 무엇을 찾을지 — 결정합니다. 인터넷 연결이나 클라우드 API가 필요 없습니다.
## 데모
▶️ **[인스타그램에서 Nightcrawler 작동 영상 보기](https://www.instagram.com/p/DYNXFvVN0c_/)**
### 작동 방식
1. **WiFi 침투** (선택 사항) — WiFi가 없는 환경에 배치된 경우, 외장 USB WiFi 어댑터를 사용하여 WPA2 네트워크를 자율적으로 크랙할 수 있습니다
2. **정찰(Reconnaissance)** — 스텔스 스캔을 사용하여 네트워크의 장치를 발견합니다
3. **열거(Enumeration)** — 발견된 서비스(웹 서버, 파일 공유, SSH, DNS 등)를 탐색합니다
4. **익스플로잇(Exploitation)** — 알려진 취약점과 기본 자격 증명을 테스트합니다
5. **보고(Reporting)** — 발견 사항과 수정 권고사항이 포함된 구조화된 침투 테스트 보고서를 생성합니다
이 에이전트는 인내심 있는 인간 침투 테스터처럼 작동합니다 — 호스트를 순회하며, 턴마다 작은 작업 하나를 수행하고, 수시간에 걸쳐 점진적으로 지식을 쌓습니다. 이는 모든 호스트를 한 번에 공격하는 기존 취약점 스캐너보다 훨씬 탐지하기 어렵게 만듭니다.
### 핵심 개념
| 용어 | 의미 |
|------|--------------|
| **드롭 박스(Drop box)** | 테스트를 자율적으로 수행하기 위해 대상 네트워크에 남겨진 장치 |
| **범위(Scope)** | 테스트가 승인된 네트워크/호스트의 집합 |
| **교전 규칙(ROE)** | 수행 가능한 작업을 명시하는 법적 문서 |
| **스텔스(Stealth)** | 네트워크 모니터링(IDS/IPS) 탐지를 피하는 기술 |
| **MCP** | Model Context Protocol — AI 도구 사용을 위한 표준 인터페이스 |
| **C2** | Command and Control — 에이전트를 모니터링하고 제어하는 웹 대시보드 |
## 아키텍처
```
┌──────────────────────────────────────────────────────────┐
│ PHONE (OnePlus 8) │
│ │
│ ┌─────────────┐ ┌──────────────────┐ │
│ │ LFM2.5 │ │ Agent Loop │ │
│ │ 1.2B model │◄───►│ (main.py) │ │
│ │ on GPU │ │ Decides what │ │
│ │ (:8080) │ │ to do next │ │
│ └─────────────┘ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Scope Proxy │ ← Safety layer │
│ │ Validates every │ Blocks out- │
│ │ command before │ of-scope │
│ │ execution │ actions │
│ └────────┬─────────┘ │
│ │ │
│ ┌────────▼─────────┐ │
│ │ Kali MCP Server │ ← Runs the │
│ │ nmap, curl, │ actual │
│ │ smbclient, ... │ commands │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Web Dashboard │ │ SQLite DB │ │
│ │ (:8888) │ │ Hosts, vulns, │ │
│ │ Monitor & steer │ │ creds, commands │ │
│ └──────────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────┘
```
전체 시스템 설계는 [docs/ARCHITECTURE.md](https://github.com/garagehq/nightcrawler/blob/main/docs/ARCHITECTURE.md)를 참조하세요.
## 기능
- **완전 자율** — 작동 중 인간 개입 불필요
- **100% 로컬 추론** — AI가 휴대폰 GPU에서 실행, 클라우드 불필요
- **범위 강제** — 범위 외 작업을 방지하는 2중 방어
- **스텔스 우선** — 느린 스캔 속도, 호스트 순환, 커버 트래픽, nmap -T2만 사용
- **27개 익스플로잇 플레이북** — 자동으로 실행되는 다단계 공격 체인
- **24,956개 항목 CVE 데이터베이스** — 버전 인식 취약점 매칭
- **웹 대시보드** — 실시간 모니터링, 호스트 관리, C2 제어
- **WiFi 침투 모드** — USB 어댑터를 통한 자율 WPA2 크랙(Pwnagotchi에서 영감)
- **수동적 발견** — mDNS/NBNS/DHCP/ARP 브로드캐스트 백그라운드 캡처
- **다중 네트워크** — 네트워크별 데이터 격리, MAC 키 호스트를 통한 DHCP 변경 대응
- **자가 복구** — 가비지 감지, 컨텍스트 리셋, 워치독, 중단 감지
- **학습 캡처** — 향후 모델 파인튜닝을 위한 성공적 상호작용 기록
- **보고서 생성** — 취약점, 익스플로잇 체인, 수정 권고사항이 포함된 다운로드 가능한 침투 테스트 보고서
전체 기능 참조는 [docs/FEATURES.md](https://github.com/garagehq/nightcrawler/blob/main/docs/FEATURES.md)를 참조하세요.
## 하드웨어
### 필수
- [Kali NetHunter](https://www.kali.org/docs/nethunter/)가 설치된 **Android 휴대폰** (OnePlus 8, Snapdragon 865에서 테스트됨)
- [Magisk](https://github.com/topjohnwu/Magisk)를 통한 **루트 액세스**
- **12GB+ RAM** (모델 약 1.3GB, Android 약 4GB, 나머지는 도구용)
### 선택 사항
- 오프라인 WiFi 침투 모드용 **USB WiFi 어댑터** (Ralink RT3572 권장)
- 모니터 모드용 MAC80211 지원 **커스텀 커널** ([빌드 가이드](https://github.com/garagehq/nightcrawler/blob/main/docs/KERNEL_BUILD_PROMPT.md))
- Tailscale을 통해 더 큰 모델로 오프로딩하기 위한 **NVIDIA AGX**
### GPU 성능
모든 추론은 Adreno 650 GPU에서 OpenCL을 통해 실행됩니다:
| 모델 | 양자화 | 프롬프트 속도 | 생성 속도 |
|-------|-------------|-------------|-----------------|
| **LFM2.5-1.2B-Instruct-Heretic** (프로덕션) | Q8_0 | 115 tok/s | 13 tok/s |
| Qwen3.5-0.8B | Q8_0 | 30.5 tok/s | 6.3 tok/s |
| Qwen3.5-4B | Q4_0 | 10.1 tok/s | 2.0 tok/s |
> **참고:** Android는 배터리 전원에서 GPU를 제한합니다(6배 느려짐). Nightcrawler에는 최대 성능을 강제하고 배터리가 ≤15%일 때 자동으로 제한하는 GPU 거버너 데몬이 포함되어 있습니다.
## 빠른 시작
```bash
# 1. 설치 (Kali NetHunter chroot 내부)
bash INSTALL.sh
# 2. llama-server 시작 대기 (부팅 후 약 5분)
curl -s http://127.0.0.1:8080/health # {"status":"ok"} 반환해야 함
# 3. 모든 서비스 시작
bash scripts/run-36h.sh
# 4. 웹 대시보드 열기 (Tailscale 네트워크의 모든 장치에서)
# https://<your-tailscale-hostname>:8888
```
### 드라이 런 (실제 명령 실행 없음)
```bash
NC_DRY_RUN=1 python3 main.py
```
이 모드는 실제 네트워크 명령을 실행하지 않고 에이전트 루프를 테스트할 수 있도록 모의 Kali 서버를 사용합니다.
### 수동 시작 (tmux 런처를 사용하지 않는 경우)
```bash
kali-server-mcp --port 5000 &
python3 scope_proxy.py --config config.yaml --port 8800 --upstream http://127.0.0.1:5000 &
bash scripts/webui-daemon.sh start
python3 main.py &
```
## 설정
배포 전에 `config.yaml`을 편집하세요:
```yaml
mission:
id: "CLIENT-YYYY-XXX" # Your engagement ID
scope:
networks: ["auto"] # "auto" = detect from wlan0 at startup
excluded_hosts: ["auto"] # "auto" = gateway + self IP
excluded_ports: [502, 503] # SCADA/ICS ports to never touch
authorization: "ROE-YYYY-XXX.pdf"
max_runtime_hours: 0 # 0 = no limit
model:
local:
ctx_size: 8192
port: 8080
```
**동적 범위 감지**는 네트워크 간 이동 시 설정 변경이 필요 없음을 의미합니다 — 에이전트는 시작 시 `wlan0`에서 현재 서브넷을 읽습니다.
## 프로젝트 구조
```
nightcrawler/
├── main.py # Entry point
├── config.yaml # Mission scope + model config
├── scope_proxy.py # Scope enforcement proxy
├── INSTALL.sh # Installer
│
├── agent/ # Core agent logic
│ ├── loop.py # Decision loop + error recovery
│ ├── planner.py # Phase state machine (recon → exploit)
│ ├── llm_client.py # LLM API client (llama.cpp / remote)
│ ├── db.py # SQLite backend (hosts, vulns, creds)
│ ├── host_memory.py # Per-host observations + auto-tagging
│ ├── cve_db.py # 24,956-entry CVE database
│ ├── attack_planner.py # Strategic directives for exploit phase
│ ├── output_parser.py # Extract structured data from tool output
│ ├── offline_manager.py # WiFi breach pipeline state machine
│ ├── net_detect.py # Auto-detect network from wlan0
│ ├── cover_traffic.py # Stealth blending with realistic web traffic
│ ├── passive_capture.py # Background tcpdump for broadcast traffic
│ └── ...
│
├── proxy/ # Scope enforcement components
│ ├── scope.py # IP/port/host validation
│ ├── rate_limiter.py # Command rate limiting + jitter
│ └── command_filter.py # Destructive command blocklist
│
├── webui/ # Web dashboard (Flask)
│ ├── server.py # API + stealth middleware
│ └── templates/index.html # Dashboard UI
│
├── data/ # Static data files
│ ├── cve_exploits.json # CVE→exploit command mappings
│ └── playbooks.json # 27 multi-step attack playbooks
│
├── prompts/ # LLM prompt templates (hot-reloadable)
├── scripts/ # Operational scripts (start, stop, watchdogs)
├── tests/ # Test suites (API, UI, offline mode)
├── kernels/ # WiFi driver modules + kernel docs
├── simulation/ # Dry-run mock server
├── docs/ # Architecture, GPU setup, features
├── logs/ # Runtime data (gitignored)
└── models/ # Model files (gitignored)
```
## 에이전트의 사고 방식
에이전트는 간단하지만 효과적인 루프를 사용합니다:
1. **대상 선택** — 가중 무작위 선택 (70% 알려진 포트가 있는 호스트, 30% 새 발견)
2. **컨텍스트 구축** — 호스트 메모리, 네트워크 관찰, 단계 지침을 프롬프트에 주입
3. **LLM에 질문** — 모델이 `REASONING: ... COMMAND: ...` 생성
4. **검증** — 범위 프록시가 명령이 범위 내에 있고 파괴적이지 않은지 확인
5. **실행** — Kali MCP 서버를 통해 명령 실행
6. **학습** — 출력 파서가 발견 사항을 추출, 호스트 메모리 업데이트
7. **컨텍스트 리셋** — 대화를 지우고, 영구 메모리 유지, 반복
1.2B 모델은 약 50%의 명령 성공률을 가집니다(크기 고유의 특성). 에이전트는 다음으로 이를 보완합니다:
- **가비지 감지** — 다양한 퓨샷 예제로 5회 연속 리셋
- **중복 감지** — 도구/대상 다양화 강제
- **시간 기반 중단 감지** — 5분 백스톱이 컨텍스트 리셋 강제
- **직접 플레이북 실행** — 다단계 공격이 LLM을 완전히 우회
## 웹 대시보드
`:8888`의 대시보드는 실시간 모니터링과 제어를 제공합니다:
- **라이브 피드** — 모든 명령, 발견 사항, 에이전트 결정
- **호스트 카드** — 포트, 서비스, 취약점을 보여주는 클릭 가능한 카드
- **네트워크 맵** — 대화형 포스 기반 그래프 (드래그, 줌, 팬)
- **취약점 상세** — CVE 태그, 익스플로잇 체인, 수정 단계
- **C2 제어** — 호스트 즐겨찾기/블랙리스트, 단계 강제, 일시정지/재개, 명령 주입
- **오프라인 모드** — 애니메이션 얼굴이 있는 Pwnagotchi 스타일 WiFi 공격 UI
대시보드는 스텔스 필터링됩니다: nginx 헤더를 스푸핑하고 대상 네트워크의 연결에 빈 404를 반환합니다.
## 테스트 결과
여러 네트워크에서 72시간 이상의 자율 작동 결과:
- 네트워크당 **30개 이상의 호스트** 발견
- **2,000개 이상의 명령** 자율 실행
- 여러 서비스에서 **10개 이상의 취약점** 발견
- 직접 실행을 통한 **6개 이상의 플레이북** 실행
- 전체 과정에서 에이전트 메모리 35-50MB 안정적 유지 (누수 없음)
## 기여
기여를 환영합니다! 지침은 [CONTRIBUTING.md](https://github.com/garagehq/nightcrawler/blob/main/CONTRIBUTING.md)를 참조하세요.
### 도움이 필요한 분야
- **모델 파인튜닝** — 명령 형식 준수율을 약 50%에서 85%+로 개선
- **새 플레이북** — 더 많은 서비스에 대한 익스플로잇 체인 추가
- **CVE 데이터베이스** — 현재 24,956개 항목 이상으로 범위 확장
- **어댑터 지원** — 더 많은 USB WiFi 칩셋 테스트
- **문서화** — 다양한 휴대폰에 대한 튜토리얼, 설정 가이드
- **테스트** — 특히 엣지 케이스에 대한 더 많은 테스트 커버리지
### 개발 환경 설정
```bash
# Clone the repo
git clone https://github.com/garagehq/nightcrawler.git
cd nightcrawler
# Dry-run mode (no real commands, no hardware needed)
NC_DRY_RUN=1 python3 main.py
# Run tests
python3 -m pytest tests/
```
## 법적 고지
**이 도구는 승인된 침투 테스트 전용입니다.** Nightcrawler를 배포하기 전에 네트워크 소유자의 서면 허가(교전 규칙)가 있어야 합니다. 소유하지 않았거나 테스트 허가가 없는 네트워크에 대한 무단 사용은 불법입니다.
## 라이선스
MIT — 자세한 내용은 [LICENSE](https://github.com/garagehq/nightcrawler/blob/main/LICENSE)를 참조하세요.
## 후원
이 프로젝트가 마음에 드신다면 커피 한 잔을 사주실 수 있습니다 ☕:
<a href="https://buymeacoffee.com/cyrilengmann" target="_blank"><img src="https://assets.kitploit.com/production/public/readmes/47403/322a7c99f1dd15a03b3c1b00b0d18ddd87443d80b823d3467a240721ae02357e.webp" alt="Buy Me A Coffee" height="50" width="210"></a>
> **[buymeacoffee.com/cyrilengmann](https://buymeacoffee.com/cyrilengmann)**