blessedrebus/krawlKrawl은 사용자 정의 가능하고 경량화된 클라우드 네이티브 웹 디셉션 서버이자 안티 크롤러로, 실제와 같은 무작위 생성 디코이 데이터와 AI 생성 HTML 템플릿을 사용하여 낮은 수준의 취약점을 가진 가짜 웹 애플리케이션을 생성합니다.
<h1 align="center">Krawl</h1>
<h3 align="center">
<a name="readme-top"></a>
<img
src="https://raw.githubusercontent.com/blessedrebus/krawl/HEAD/img/krawl-svg.svg"
height="250"
>
</h3>
<div align="center">
<p align="center">
기만적인 웹 페이지, 가짜 자격 증명, 카나리 토큰을 통해 공격자와 웹 크롤러의 악성 활동을 탐지하고 추적하도록 설계된 현대적이고 사용자 정의 가능한 웹 허니팟 서버입니다.
</p>
<div align="center">
<a href="https://github.com/blessedrebus/krawl/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/blessedrebus/krawl" alt="License">
</a>
<a href="https://github.com/blessedrebus/krawl/releases">
<img src="https://img.shields.io/github/v/release/blessedrebus/krawl" alt="Release">
</a>
</div>
<div align="center">
<a href="https://ghcr.io/blessedrebus/krawl">
<img src="https://img.shields.io/badge/ghcr.io-krawl-blue" alt="GitHub Container Registry">
</a>
<a href="https://kubernetes.io/">
<img src="https://img.shields.io/badge/kubernetes-ready-326CE5?logo=kubernetes&logoColor=white" alt="Kubernetes">
</a>
<a href="https://github.com/BlessedRebuS/Krawl/pkgs/container/krawl-chart">
<img src="https://img.shields.io/badge/helm-chart-0F1689?logo=helm&logoColor=white" alt="Helm Chart">
</a>
</div>
</div>
## 목차
- [데모](#demo)
- [Krawl이란?](#what-is-krawl)
- [Krawl 대시보드](#krawl-dashboard)
- [배포 모드](#deployment-modes)
- [Krawl 차단 목록](#krawl-banlist)
- [빠른 시작](#quickstart)
- [Docker 실행](#docker-run)
- [Docker Compose](#docker-compose)
- [Kubernetes](#kubernetes)
- [Uvicorn (Python)](#uvicorn-python)
- [구성](#configuration)
- [config.yaml](#configuration-via-configyaml)
- [환경 변수](#configuration-via-environmental-variables)
- [악성 IP 차단](#use-krawl-to-ban-malicious-ips)
- [IP 평판](#ip-reputation)
- [리버스 프록시 또는 CDN 뒤에서 실행](#running-behind-a-reverse-proxy-or-cdn)
- [메트릭 및 모니터링](#metrics--monitoring)
- [추가 문서](#additional-documentation)
- [AI를 이용한 기만](#ai-generated-deception-pages)
- [기여](#contributing)
## 데모
팁: 추가 재미를 위해 `robots.txt` 경로를 크롤링해 보세요
### Krawl URL: [http://demo.krawlme.com](http://demo.krawlme.com)
### 대시보드 보기 [http://demo.krawlme.com/das_dashboard](http://demo.krawlme.com/das_dashboard)
## Krawl이란?
**Krawl**은 악의적인 공격자, 웹 크롤러 및 자동화된 스캐너를 탐지하고 지연시키며 분석하도록 설계된 클라우드 네이티브 기만 서버입니다.
관리자 패널, 구성 파일, 노출된 가짜 자격 증명과 같은 손쉬운 먹잇감으로 가득 찬 현실적인 가짜 웹 애플리케이션을 생성하여 의심스러운 활동을 유인하고 식별합니다.
공격자의 리소스를 낭비함으로써 Krawl은 악의적인 행동과 합법적인 크롤러를 명확히 구분하는 데 도움을 줍니다.
주요 기능:
- **[AI 생성 기만 페이지](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md)**: **공격자가 가짜 취약 공격 표면을 생성하도록 돕게 하세요**
- **스파이더 트랩 페이지**: [spidertrap 프로젝트](https://github.com/adhdproject/spidertrap)를 기반으로 크롤러 리소스를 낭비시키는 무한한 무작위 링크
- **가짜 로그인 페이지**: WordPress, phpMyAdmin, 관리자 패널
- **허니팟 경로**: 스캐너를 잡기 위해 robots.txt에 광고됨
- **가짜 자격 증명**: 실제처럼 보이는 사용자 이름, 비밀번호, API 키
- **[카나리 토큰](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md) 통합**: 외부 경고 트리거
- **무작위 서버 헤더**: 서버 헤더와 버전을 기반으로 공격을 혼란시킴
- **실시간 대시보드**: 의심스러운 활동 모니터링
- **사용자 정의 가능한 단어 목록**: 쉬운 JSON 기반 구성
- **무작위 오류 주입**: 실제 서버 동작 모방
리버스 프록시를 사용하여 다른 서비스와 함께 Krawl을 쉽게 노출시켜 웹 크롤러와 악의적인 사용자로부터 서비스를 보호할 수 있습니다. 자세한 내용은 [리버스 프록시 문서](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md)를 참조하세요.
## Krawl 대시보드
Krawl은 시작 시 생성되는 **무작위 비밀 경로** 또는 `KRAWL_DASHBOARD_SECRET_PATH`를 통해 구성된 **사용자 정의 경로**에서 접근할 수 있는 포괄적인 대시보드를 제공합니다. 이를 통해 허니팟을 스캔하는 공격자로부터 대시보드를 숨길 수 있습니다.
대시보드는 여섯 개의 탭으로 구성됩니다:
- **개요**: 공격 활동에 대한 상위 수준 보기: IP 출처의 대화형 지도, 최근 의심스러운 요청, 상위 IP, User-Agent 및 경로.
- **공격**: 캡처된 자격 증명, 허니팟 트리거, 탐지된 공격 유형(SQLi, XSS, 경로 탐색 등)에 대한 상세 분석과 차트 및 표.
- **위협**: TLSH 퍼지 해시로 캠페인별로 그룹화된 페이로드로, 웹셸과 그 수정 변형이 서로 무관한 적중이 아닌 하나의 캠페인으로 읽히며, 캡처된 모든 파일의 색인이 포함됩니다.
- **IP 인사이트**: 선택한 IP에 대한 심층 포렌식 보기: 지리적 위치, ISP/ASN 정보, 평판 플래그, 행동 타임라인, 공격 유형 분포, 리퍼러 기록, 캡처된 파일 및 자격 증명, 전체 접근 기록.
또한 대시보드 비밀번호로 인증하면 보호된 탭을 사용할 수 있습니다:
- **추적된 IP**: 시간 경과에 따라 모니터링하려는 IP 주소의 감시 목록을 유지합니다.
- **IP 차단 목록**: IP 차단을 관리하고, 탐지된 공격자를 확인하며, 차단 목록을 raw 또는 IPTables 형식으로 내보냅니다.
- **타임아웃된 IP**: 현재 타르핏에 보관 중인 IP를 검토하고, 그렇지 않아야 할 IP는 예외 처리합니다.
- **기만**: AI 생성 페이지를 관리하고, 내보내거나 새 페이지를 가져옵니다.
- **웹훅**: 차단을 CloudFlare 및 기타 방화벽으로 전달합니다.
헤더 아이콘은 API 문서, 차단 목록 내보내기, 실행 중인 구성을 보여주는 설정 패널, 그리고 예약된 작업을 필요 시 실행하기 위한 유지 관리 페이지를 엽니다.
자세한 내용은 [대시보드 문서](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md)를 참조하세요.
## 배포 모드
Krawl은 `config.yaml`의 `mode` 설정 또는 `KRAWL_MODE` 환경 변수로 제어되는 두 가지 배포 모드를 지원합니다.
| | 독립 실행형 | 확장 가능 |
|---|---|---|
| **데이터베이스** | SQLite (WAL 모드) | PostgreSQL |
| **캐시** | 인메모리 Python dict | Redis (다계층 TTL) |
| **복제본** | 1 (단일 인스턴스) | 1+ (수평 확장) |
| **외부 의존성** | 없음 | PostgreSQL + Redis |
| **적합한 용도** | 개발, 홈랩, 50만 건 미만 요청 | 프로덕션, HA, 50만 건 초과 요청 |
**독립 실행형**: 요청 수가 적은 개발 환경이나 홈랩에 이상적입니다. 추가 구성이 필요 없으며, Krawl을 실행하기만 하면 작동합니다.
- 외부 의존성 없는 단일 컨테이너 배포
- 낮은 RAM 및 리소스 사용량
**확장 가능**: 프로덕션 환경이나 고트래픽 허니팟을 위해 설계되었습니다. Helm 차트는 기본적으로 이 모드를 사용합니다.
- Redis 다계층 캐싱 덕분에 더 빠르고 반응성이 좋은 대시보드
- PostgreSQL 앞에서 Redis가 핫 패스 캐시 역할을 하여 디스크 I/O 감소
- 로드 밸런서 뒤에서 Krawl 복제본 수를 늘리는 수평 확장
자세한 구성, Docker Compose 예제, Kubernetes/Helm 설정, 단계별 마이그레이션 지침은 [배포 모드 문서](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md)를 참조하세요.
## Krawl 차단 목록
Krawl은 **허니팟 트랩을 트리거한 공격자**의 IP 주소로 구성된 정기적으로 업데이트되는 [`banlist.txt`](https://github.com/blessedrebus/krawl/blob/main/banlist.txt)를 유지합니다. 차단 목록은 매주 게시되며 다운로드할 수 있어, Krawl을 사용하지 않더라도 커뮤니티가 알려진 악성 행위자를 선제적으로 차단할 수 있도록 돕습니다.
차단 목록은 다음에서 직접 가져올 수도 있습니다:
[https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw](https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw).
### 인스턴스 간 차단 목록 공유
Krawl 인스턴스는 차단 목록을 연합할 수 있습니다: 각 인스턴스는 인증되지 않은 경로에 자체 목록을 게시하고 다른 인스턴스(또는 일반 텍스트 IP 목록)의 목록을 가져올 수 있습니다. 가져온 IP는 로컬 차단 결정에 병합되어 대시보드에 표시됩니다.```yaml
banlist:
# Public, unauthenticated download path for this instance's banlist.
# Supports the same ?categories= and ?fwtype= parameters as the main API.
# Empty = disabled.
export_path: "/public_banlist.txt"
# Upstream banlists to fetch and merge. Plain ".txt" lists work too.
sources:
- "https://demo.krawlme.com/das_dashboard/api/export-ips?categories=attacker&fwtype=raw"
- "https://krawl.example.com/public_banlist.txt"
refresh_interval: 3600 # seconds between fetches
```
## 빠른 시작
### Docker 실행
최신 이미지로 Krawl을 독립 실행 모드로 실행하세요:```bash
docker run -d \
-p 5000:5000 \
-e KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard" \
-e KRAWL_DASHBOARD_PASSWORD="my-secret-password" \
-v krawl-data:/app/data \
--name krawl \
ghcr.io/blessedrebus/krawl:latest
```
`http://localhost:5000`에서 서버에 접속합니다.
### Docker Compose
두 가지 배포 모드 중 하나로 `docker-compose.yaml`을 생성합니다.
**Standalone**: Sqlite 스토리지를 사용하는 Krawl 서버만:```yaml
services:
krawl:
image: ghcr.io/blessedrebus/krawl:latest
container_name: krawl-server
ports:
- "5000:5000"
environment:
- CONFIG_LOCATION=config.yaml
# - KRAWL_DASHBOARD_PASSWORD=my-secret-password
volumes:
- ./config.yaml:/app/config.yaml:ro
- krawl-data:/app/data
restart: unless-stopped
volumes:
krawl-data:
```
**확장 가능**: PostgreSQL 및 Redis 사용 시:
> [!CAUTION]
> 아래 예시는 **기본 비밀번호**(`krawl`/`krawl`)를 사용합니다. **프로덕션에 배포하기 전에 반드시 변경하세요.**```yaml
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_DB: krawl
POSTGRES_USER: krawl
POSTGRES_PASSWORD: krawl
volumes:
- postgres_data:/var/lib/postgresql/data
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U krawl -d krawl"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
restart: unless-stopped
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s
timeout: 5s
retries: 5
krawl:
image: ghcr.io/blessedrebus/krawl:latest
container_name: krawl-server
ports:
- "5000:5000"
environment:
- CONFIG_LOCATION=config.yaml
- KRAWL_MODE=scalable
- KRAWL_POSTGRES_HOST=postgres
- KRAWL_POSTGRES_PORT=5432
- KRAWL_POSTGRES_USER=krawl
- KRAWL_POSTGRES_PASSWORD=krawl
- KRAWL_POSTGRES_DATABASE=krawl
- KRAWL_REDIS_HOST=redis
- KRAWL_REDIS_PORT=6379
# - KRAWL_DASHBOARD_PASSWORD=my-secret-password
volumes:
- ./config.yaml:/app/config.yaml:ro
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
volumes:
postgres_data:
redis_data:
```
배포하려면 다음을 실행하세요.```bash
docker compose up -d
```
프로덕션 환경에 바로 사용할 수 있는 compose 파일은 [`docker/`](https://github.com/blessedrebus/krawl/blob/main/docker) 디렉터리에도 있습니다. **개발**용(소스에서 빌드하고 핫 리로드 지원)으로는 [`docker/dev/`](https://github.com/blessedrebus/krawl/blob/main/docker/dev)의 compose 파일을 사용하세요.
두 모드에 대한 자세한 내용은 [배포 모드](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md)를 참고하세요.
### Kubernetes
**Krawl은 Kubernetes에서도 네이티브로 사용할 수 있습니다**. 설치는 [매니페스트를 통한 방법](https://github.com/blessedrebus/krawl/blob/main/kubernetes/README.md) 또는 [Helm 차트를 사용하는 방법](https://github.com/blessedrebus/krawl/blob/main/helm/README.md) 중 하나로 할 수 있습니다.
Helm 차트는 PostgreSQL과 Redis가 함께 포함된 **확장 가능 모드를 기본값으로 사용합니다**:```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.4.0 \
-n krawl-system --create-namespace \
--set postgres.password=your-password \
--set redis.password=your-redis-password \
--set dashboardPassword=your-dashboard-password \
--set config.dashboard.secret_path=/my-secret-dashboard
```
두 모드 모두에 대해 최소 예제 values 파일이 제공됩니다:
- [`values-minimal.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-minimal.yaml) ---> 확장 가능(기본값)
- [`values-standalone.yaml`](https://github.com/blessedrebus/krawl/blob/main/helm/values-standalone.yaml) ---> 독립 실행형
전체 구성 및 마이그레이션 지침은 [배포 모드](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md)와 [차트 문서](https://github.com/blessedrebus/krawl/blob/main/helm/README.md)를 참조하세요.
### Uvicorn (Python)
로컬 개발 또는 테스트를 위해 Python 3.13+ 및 uvicorn으로 Krawl을 직접 실행하세요:```bash
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 5000 --app-dir src --no-server-header
```
`http://localhost:5000`에서 서버에 접속합니다
## 구성
Krawl은 **환경 변수가 구성 파일보다 우선하는** **구성 계층 구조**를 사용합니다. 이 방식은 Docker 배포 및 빠른 즉시 사용자 정의에 권장됩니다.
### config.yaml을 통한 구성
Docker Compose 또는 Helm 차트 배포와 같은 고급 구성에는 [config.yaml](https://github.com/blessedrebus/krawl/blob/main/config.yaml) 파일을 사용할 수 있습니다.
### 환경 변수를 통한 구성
모든 설정은 환경 변수로 제공할 수 있으며, 이는 `config.yaml`을 재정의합니다.
변수 이름은 `KRAWL_`에 설정 경로를 대문자로 붙인 형태이므로, `dashboard.password`는
`KRAWL_DASHBOARD_PASSWORD`가 됩니다.
<details>
<summary><b>서버 및 링크 생성</b> (11개 변수)</summary>
Krawl이 자신을 표시하고 생성된 페이지의 미로를 구성하는 방식입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | yaml 구성 파일 경로 | `config.yaml` |
| `KRAWL_PORT` | 서버 수신 포트 | `5000` |
| `KRAWL_DELAY` | 응답 지연(밀리초) | `100` |
| `KRAWL_SERVER_HEADER` | 기만용 HTTP Server 헤더 | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | `min,max` 형식의 링크 길이 범위 | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | `min,max` 형식의 페이지당 링크 수 | `10,15` |
| `KRAWL_CHAR_SPACE` | 링크 생성에 사용되는 문자 | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | 초기 카운터 값 | `10` |
| `KRAWL_PROBABILITY_ERROR_CODES` | 오류 응답 확률 (0-100%) | `0` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | 악성 IP에 무한 페이지 제공 | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | 크롤러에 대한 최대 페이지 제한 | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | 속도 제한된 IP에 대한 차단 지속 시간(초) | `600` |
</details>
<details>
<summary><b>대시보드, 메트릭 및 로깅</b> (13개 변수)</summary>
대시보드 접근, 캐시 워밍업, Prometheus 및 로그 레벨입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_DASHBOARD_SECRET_PATH` | 사용자 정의 대시보드 경로 | 자동 생성 |
| `KRAWL_DASHBOARD_PASSWORD` | 보호된 대시보드 패널의 비밀번호 | 자동 생성 |
| `KRAWL_DASHBOARD_CACHE_WARMUP` | 즉각적인 페이지 로드를 위해 5분마다 대시보드 데이터를 미리 계산 | `true` |
| `KRAWL_DASHBOARD_WARMUP_PAGES` | 테이블 패널당 미리 워밍할 페이지 수 | `10` |
| `KRAWL_DASHBOARD_WARMUP_AGGREGATION` | 쿼리 없는 제공을 위해 전체 top_paths/top_ua 집계를 미리 계산 | `false` |
| `KRAWL_DASHBOARD_TOP_N_MIN_COUNT` | 상위 경로/사용자 에이전트 패널의 최소 접근 횟수 (비활성화하려면 1로 설정) | `5` |
| `KRAWL_DASHBOARD_BRAND_NAME` | 대시보드 워드마크 및 제목에 표시되는 이름 | `Krawl` |
| `KRAWL_DASHBOARD_BRAND_URL` | 워드마크가 연결되는 위치 (비어 있으면 일반 텍스트로 렌더링) | Krawl의 저장소 |
| `KRAWL_DASHBOARD_BRAND_LOGO` | GitHub 마크 대신 표시되는 이미지 URL | 설정 안 됨 |
| `KRAWL_DASHBOARD_BRAND_SHOW_VERSION` | 이름 옆에 버전 표시 | `true` |
| `KRAWL_DASHBOARD_BRAND_CONTACT` | 워드마크 아래에 표시되는 연락처 (주소, URL 또는 일반 텍스트) | 설정 안 됨 |
| `KRAWL_METRICS_ENABLED` | `/<dashboard_path>/metrics`에서 Prometheus 메트릭 노출 | `true` |
| `KRAWL_LOG_LEVEL` | 애플리케이션 로그 레벨 (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
</details>
<details>
<summary><b>데이터베이스, 보존 및 백업</b> (12개 변수)</summary>
저장 위치, 데이터 보존 기간 및 덤프 작업입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | 데이터베이스 파일 위치 | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | 의심스러운 요청만 접근 로그에 저장 | `false` |
| `KRAWL_MAP_TILE_URL` | 대시보드 지도의 타일 URL 템플릿 (`{z}/{x}/{y}`, 선택적 `{s}`/`{r}`) | Esri dark canvas |
| `KRAWL_MAP_TILE_ATTRIBUTION` | 지도에 표시되는 저작자 표시 | Esri/OSM |
| `KRAWL_MAP_API_KEY` | 모든 타일 요청에 쿼리 매개변수로 추가됨 — CARTO에서 요구 | _(비어 있음)_ |
| `KRAWL_MAP_API_KEY_PARAM` | 해당 쿼리 매개변수의 이름 (`api_key`, `apikey`, `key`) | `api_key` |
| `KRAWL_IPV6_IGNORE` | IPv6 요청을 완전히 무시: stdout에 계속 로깅되지만 저장, 차단 확인 또는 내보내기되지 않음 | `false` |
| `KRAWL_IPV6_PURGE_EXISTING` | 다음 시작 시 기존 IPv6 행도 삭제 (되돌릴 수 없음; `KRAWL_IPV6_IGNORE` 필요) | `false` |
| `KRAWL_DATABASE_RETENTION_DAYS` | 데이터베이스에 데이터를 보존할 일수 | `30` |
| `KRAWL_BACKUPS_PATH` | 데이터베이스 덤프가 저장되는 경로 | `backups` |
| `KRAWL_BACKUPS_CRON` | 백업 작업 일정을 제어하는 cron 표현식 | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | db 덤프 작업을 활성화하는 불리언 | `true` |
</details>
<details>
<summary><b>트랩: 타르핏, 기만 페이지 및 카나리</b> (6개 변수)</summary>
선택적 트랩 및 공격자에게 제공되는 페이지입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_TARPIT_ENABLED` | 느린 응답과 무작위 텍스트로 AI 에이전트를 가둠 | `false` |
| `KRAWL_TARPIT_DELAY_SECONDS` | 타르핏이 활성화된 경우 응답당 추가되는 지연(초) | `5` |
| `KRAWL_DECEPTION_IMPORT_PAGES` | 시작 시 `src/templates/deception/`에서 기만 페이지를 자동 가져오기 | `true` |
| `KRAWL_CUSTOM_TEMPLATE_PATH` | 컨테이너 내부의 사용자 정의 HTML 템플릿 경로. 템플릿에는 `{counter}` 및 `{content}` 자리 표시자가 포함되어야 합니다. | `/templates/custom_page.html` |
| `KRAWL_CANARY_TOKEN_URL` | 외부 카나리 토큰 URL | 없음 |
| `KRAWL_CANARY_TOKEN_TRIES` | 카나리 토큰을 표시하기 전까지의 요청 수 | `10` |
</details>
<details>
<summary><b>IP 평판 분석기</b> (6개 변수)</summary>
IP가 어떻게 분류되는지를 결정하는 임계값입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | 위험한 HTTP 메서드 감지 임계값 | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | robots.txt 위반 임계값 | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | 타이밍에 대한 변동 계수 임계값 | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | 요청 타이밍 분석을 위한 시간 창(초) | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | 여러 사용자 에이전트 감지 임계값 | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | 공격 URL 감지 임계값 | `1` |
</details>
<details>
<summary><b>위협 인텔리전스 캡처</b> (4개 변수)</summary>
캡처된 페이로드(파일 및 플래그된 요청 본문)를 퍼지 해시하고
거의 중복되는 변형을 캠페인 클러스터로 그룹화합니다. `py-tlsh`가 필요합니다.
해싱은 예약된 `hash-payloads` 백그라운드 작업(참조:
`src/tasks/hash_payloads.py`)으로 실행되며, 이 작업은 각 캡처된 공격을 한 번 해시합니다 —
수집 시점의 새로운 적중과 `payload_hash_watermark` 하이 워터 마크로 추적되는
기존 기록의 일회성 역방향 스윕 — 그런 다음 다이제스트를 반복 패턴 캠페인으로 클러스터링합니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_TLSH_ENABLED` | 거의 중복 클러스터링을 위해 업로드된 파일 및 플래그된 요청 본문을 TLSH로 해시 | `true` |
| `KRAWL_TLSH_CLUSTER_THRESHOLD` | 페이로드가 기존 캠페인에 합류하는 TLSH 거리 (0 = 동일 바이트; 웹셸의 변형은 일반적으로 diff < 100) | `150` |
| `KRAWL_TLSH_CAMPAIGN_MIN_EVENTS` | 캠페인이 Threats 탭에 나타나기 전에 페이로드가 확인되어야 하는 횟수 | `10` |
| `KRAWL_REFERER_ENABLED` | 미끼 체인 추적을 위해 접근 로그에 인바운드 HTTP Referer 기록 | `true` |
</details>
<details>
<summary><b>차단 목록 및 무시된 IP</b> (4개 변수)</summary>
다른 인스턴스와 차단 목록 공유, 그리고 절대 추적하지 않을 트래픽입니다.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | 절대 추적, 차단 또는 내보내지 않는 쉼표로 구분된 IP/CIDR | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | 공개 차단 목록 다운로드 경로, 예: `/public_banlist.txt` (비어 있으면 비활성화) | `""` |
| `KRAWL_BANLIST_SOURCES` | 가져와 병합할 쉼표로 구분된 업스트림 차단 목록 URL | Krawl 커뮤니티 차단 목록 |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | 업스트림 차단 목록 가져오기 간격(초) | `3600` |
</details>
<details>
<summary><b>AI 생성 기만 페이지</b> (10개 변수)</summary>
[AI 생성 문서](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md)를 참조하세요.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_AI_ENABLED` | AI 생성 기만 페이지 활성화 | `false` |
| `KRAWL_AI_PROVIDER` | AI 제공자 (`"openrouter"` 또는 `"openai"`) | `"openrouter"` |
| `KRAWL_AI_OPENAI_BASE_URL` | 사용자 정의 API 엔드포인트를 위한 선택적 OpenAI Base URL | `"https://api.openai.com/v1"` |
| `KRAWL_AI_API_KEY` | AI 제공자용 API 키 | `None` |
| `KRAWL_AI_MODEL` | 페이지 생성에 사용할 AI 모델 | `"nvidia/nemotron-3-super-120b-a12b:free"` |
| `KRAWL_AI_TIMEOUT` | AI API 호출의 요청 타임아웃(초) | `60` |
| `KRAWL_AI_MAX_DAILY_REQUESTS` | 하루 최대 AI 생성 페이지 수 (0 = 무제한) | `0` |
| `KRAWL_AI_PROMPT` | AI 페이지 생성을 위한 사용자 정의 프롬프트 템플릿 | 기본 프롬프트 |
| `KRAWL_AI_REASONING_ENABLED` | 추론 토큰 활성화 (OpenRouter 추론 모델 전용) | `false` |
| `KRAWL_AI_REASONING_EFFORT` | 추론 노력 (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) | `"medium"` |
</details>
<details>
<summary><b>확장 모드: PostgreSQL 및 Redis</b> (13개 변수)</summary>
`KRAWL_MODE=scalable`인 경우에만 사용됩니다. [배포 모드](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md)를 참조하세요.
| 환경 변수 | 설명 | 기본값 |
|----------------------|-------------|---------|
| `KRAWL_MODE` | 배포 모드 (`standalone` 또는 `scalable`) | `standalone` |
| `KRAWL_POSTGRES_HOST` | PostgreSQL 호스트 이름 | `localhost` |
| `KRAWL_POSTGRES_PORT` | PostgreSQL 포트 | `5432` |
| `KRAWL_POSTGRES_USER` | PostgreSQL 사용자 이름 | `krawl` |
| `KRAWL_POSTGRES_PASSWORD` | PostgreSQL 비밀번호 | `krawl` |
| `KRAWL_POSTGRES_DATABASE` | PostgreSQL 데이터베이스 이름 | `krawl` |
| `KRAWL_REDIS_HOST` | Redis 호스트 이름 | `localhost` |
| `KRAWL_REDIS_PORT` | Redis 포트 | `6379` |
| `KRAWL_REDIS_DB` | Redis 데이터베이스 번호 | `0` |
| `KRAWL_REDIS_PASSWORD` | Redis 비밀번호 | 없음 |
| `KRAWL_REDIS_CACHE_TTL` | 대시보드 워밍업 데이터의 TTL(초) | `600` |
| `KRAWL_REDIS_HOT_TTL` | 핫 패스 데이터(차단 정보, IP 카테고리)의 TTL(초) | `30` |
| `KRAWL_REDIS_TABLE_TTL` | 페이지네이션된 대시보드 테이블의 TTL(초) | `120` |
</details>
예를 들어```bash
# Set canary token
export CONFIG_LOCATION="config.yaml"
export KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"
# Set number of pages range (min,max format)
export KRAWL_LINKS_PER_PAGE_RANGE="5,25"
# Set analyzer thresholds
export KRAWL_HTTP_RISKY_METHODS_THRESHOLD="0.2"
export KRAWL_VIOLATED_ROBOTS_THRESHOLD="0.15"
# Set custom dashboard path and password
export KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard"
export KRAWL_DASHBOARD_PASSWORD="my-secret-password"
```
환경 변수를 사용한 Docker 실행 예시(독립 실행 모드):```bash
docker run -d \
-p 5000:5000 \
-e KRAWL_MODE=standalone \
-e KRAWL_PORT=5000 \
-e KRAWL_DELAY=100 \
-e KRAWL_DASHBOARD_PASSWORD="my-secret-password" \
-e KRAWL_CUSTOM_TEMPLATE_PATH="/templates/custom_page.html" \
-e KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url" \
--name krawl \
ghcr.io/blessedrebus/krawl:latest
```
## Krawl을 사용하여 악성 IP 차단하기
Krawl은 평판 기반 시스템을 사용하여 공격자 IP 주소를 분류하며, 방화벽 통합을 위한 IP 목록을 내보내는 두 가지 방법을 제공합니다.
`/api/export-ips` 엔드포인트는 데이터베이스를 직접 쿼리하며 IP 카테고리(`attacker`, `bad_crawler`, `regular_user`, `good_crawler`)와 출력 형식(`raw`, `iptables`, `nftables`)으로 필터링을 지원합니다:```bash
curl "https://your-krawl-instance/<DASHBOARD-PATH>/api/export-ips?categories=attacker&fwtype=raw"
```
이를 통해 다양한 플랫폼에서 악성 트래픽을 자동으로 차단할 수 있습니다:
* [OPNsense 및 pfSense](https://ipv64.net/v64_blocklist_integration_guide)
* [RouterOS](https://rentry.co/krawl-routeros)
* [IPtables](https://github.com/blessedrebus/krawl/blob/main/plugins/iptables/README.md) 및 [Nftables](https://github.com/blessedrebus/krawl/blob/main/plugins/nftables/README.md)
* [Fail2Ban](https://github.com/blessedrebus/krawl/blob/main/plugins/fail2ban/README.md)
전체 API 매개변수, 예제, 사용자 정의 방화벽 형식 추가에 대해서는 [방화벽 내보내기 문서](https://github.com/blessedrebus/krawl/blob/main/docs/firewall-exporters.md)를 참조하세요.
Krawl은 차단된 IP를 Cloudflare 계정 IP 목록에 직접 푸시하여 WAF 규칙에서 사용할 수도 있습니다. 동기화는 백그라운드 작업으로 실행되며 구성 가능한 간격으로 전체 교체 방식으로 목록을 업데이트합니다. [Cloudflare 차단 목록 동기화](https://github.com/blessedrebus/krawl/blob/main/docs/cloudflare_banlist.md) 문서를 참조하세요.
## IP 평판
Krawl은 [최근 트래픽을 분석하여 IP 평판 점수를 구축하고 지속적으로 업데이트하는 작업을 사용합니다](https://github.com/blessedrebus/krawl/blob/main/src/tasks/analyze_ips.py). 이 작업은 주기적으로 실행되며 여러 행동 지표를 기반으로 각 활성 IP 주소를 평가하여 공격자, 크롤러 또는 일반 사용자로 분류합니다. 임계값은 완전히 사용자 정의할 수 있습니다.
분석에는 다음이 포함됩니다:
- **위험한 HTTP 메서드 사용** (예: POST, PUT, DELETE 비율)
- **Robots.txt 위반**
- **요청 타이밍 이상** (버스트 또는 불규칙한 패턴)
- **User-Agent 일관성**
- **공격 URL 탐지** (예: SQL 인젝션, XSS 패턴)
각 신호는 평판 카테고리를 할당하는 가중치 점수 모델에 기여합니다:
- `attacker`
- `bad_crawler`
- `good_crawler`
- `regular_user`
- `unknown` (데이터가 불충분한 경우)
결과 점수와 지표는 데이터베이스에 저장되며 Krawl에서 대시보드, 평판 추적, IP 차단 또는 방화벽 통합과 같은 자동 완화 조치를 구동하는 데 사용됩니다.
## AI 생성 기만 페이지
Krawl은 **OpenRouter** 또는 **OpenAI** API의 AI 모델을 사용하여 사실적인 기만 페이지를 자동으로 생성할 수 있습니다. 이 기능은 수동으로 페이지를 만들지 않고도 공격자를 속이기 위해 즉석에서 독특하고 그럴듯한 허니팟 페이지를 생성합니다.
**주요 기능:**
- **동적 생성**: 모든 요청 경로에 대해 고유한 HTML 페이지 생성
- **스마트 캐싱**: 중복 API 호출을 피하기 위해 생성된 페이지 캐시
- **일일 속도 제한**: 구성 가능한 요청 제한으로 API 비용 제어
- **다중 제공자**: OpenRouter(무료 옵션) 및 OpenAI 지원
- **정상적 폴백**: 비활성화되거나 제한에 도달한 경우 표준 허니팟으로 폴백
- **캐시 제공**: AI가 비활성화된 경우에도 이전에 생성된 페이지 제공
**빠른 설정:**```yaml
ai:
enabled: true
provider: "openrouter"
openai_base_url: "your-custom-base-url"
api_key: "your-api-key"
model: "nvidia/nemotron-3-super-120b-a12b:free"
timeout: 60
max_daily_requests: 10
```
자세한 구성 및 사용법은 [AI 생성 문서](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md)를 참조하세요.
PR을 열어 **기만 템플릿을 기여**할 수도 있습니다. [기만 템플릿 기여](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md#contributing-deception-templates-via-pr)를 참조하세요.
## 리버스 프록시 또는 CDN 뒤에서 실행하기
**NGINX, Traefik, 그리고 CloudFlare 같은 기타 프록시**는 Krawl이 실제 IP를 확인할 수 있도록 헤더 포워딩이 필요합니다. 구성 예시와 전체 헤더 목록은 [리버스 프록시 문서](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md)를 참조하세요.
## 메트릭 및 모니터링
```
---
[Read more](https://github.com/blessedrebus/krawl)