## クイックスタート

### 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

**スケーラブル**: 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:

本番環境向けの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.3.1 \
  -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

`http://localhost:5000` でサーバーにアクセスします。

## 設定
Krawl は**設定階層**を使用し、**環境変数が設定ファイルよりも優先されます**。このアプローチは、Docker デプロイや迅速な初期カスタマイズに推奨されます。

### config.yaml による設定
Docker Compose や Helm chart デプロイなどの高度な設定には、[config.yaml](https://github.com/blessedrebus/krawl/blob/main/config.yaml) ファイルを使用できます。

### 環境変数による設定

すべての設定は環境変数として指定でき、`config.yaml` を上書きします。
変数名は `KRAWL_` に設定パスを大文字で連結したもので、`dashboard.password` は
`KRAWL_DASHBOARD_PASSWORD` になります。

<details>
<summary><b>サーバーとリンク生成</b>（12 変数）</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>（8 変数）</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_METRICS_ENABLED` | `/<dashboard_path>/metrics` で Prometheus メトリクスを公開 | `true` |
| `KRAWL_LOG_LEVEL` | アプリケーションログレベル（`DEBUG`、`INFO`、`WARNING`、`ERROR`） | `INFO` |

</details>

<details>
<summary><b>データベース、保持、バックアップ</b>（6 変数）</summary>

保存場所、データ保持期間、ダンプジョブ。

| 環境変数 | 説明 | デフォルト |
|----------------------|-------------|---------|
| `KRAWL_DATABASE_PATH` | データベースファイルの場所 | `data/krawl.db` |
| `KRAWL_DATABASE_PERSIST_SUSPICIOUS_ONLY` | 疑わしいリクエストのみアクセスログに永続化 | `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 | None |
| `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>禁止リストと無視 IP</b>（4 変数）</summary>

他のインスタンスとの禁止リスト共有、および追跡しないトラフィック。

| 環境変数 | 説明 | デフォルト |
|----------------------|-------------|---------|
| `KRAWL_IGNORED_IPS` | 追跡、禁止、エクスポートされないカンマ区切りの IP/CIDR | ループバック、RFC1918、リンクローカル、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` | 1 日あたりの 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 パスワード | None |
| `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"

## Krawlを使用して悪意のあるIPをブロックする
Krawlは、レピュテーションベースのシステムを使用して攻撃者のIPアドレスを分類し、ファイアウォール統合のためにIPリストをエクスポートする2つの方法を提供します。

`/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"

詳細な設定と使用方法については、[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)を参照してください。

## メトリクスとモニタリング

Krawlは、`/<dashboard_secret_path>/metrics`で[Prometheus](https://prometheus.io/)メトリクスを公開し（デフォルトで有効）、[`grafana-dashboard.json`](https://github.com/blessedrebus/krawl/blob/main/grafana-dashboard.json)にインポート可能な[Grafana](https://grafana.com/)ダッシュボードが同梱されています。

完全なメトリクスリスト、Grafanaのインポート手順、およびPrometheus / Kubernetes（`ServiceMonitor`）のスクレイピング設定については、[モニタリングのドキュメント](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md)を参照してください。

## 追加ドキュメント

| トピック | 説明 |
|-------|-------------|
| [AI生成](https://github.com/blessedrebus/krawl/blob/main/docs/ai_generation.md) | OpenRouterまたはOpenAIを使用してAI生成の偽装ページを設定する |
| [偽装ページ](https://github.com/blessedrebus/krawl/blob/main/docs/deception_pages.md) | 偽装ページの管理、インポート、エクスポート、一括操作、日付ベースのフィルタリング |
| [デプロイメントモード](https://github.com/blessedrebus/krawl/blob/main/docs/deployment-modes.md) | スタンドアロン（SQLite）モードとスケーラブル（PostgreSQL + Redis）モード、設定、データ移行 |
| [ハニーポット](https://github.com/blessedrebus/krawl/blob/main/docs/honeypot.md) | 偽ログイン、ディレクトリリスト、資格情報ファイル、SQLi/XSS/XXE/コマンドインジェクションの罠などのハニーポットページの完全な概要 |
| [ダッシュボード](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard.md) | リアルタイムモニタリングダッシュボードへのアクセスと操作 |
| [ダッシュボードAPI](https://github.com/blessedrebus/krawl/blob/main/docs/dashboard-api.md) | Krawl独自のJSON API：エンドポイントリファレンス、認証、対話型OpenAPIドキュメント、添付ファイルのダウンロード |
| [外部API](https://github.com/blessedrebus/krawl/blob/main/docs/api.md) | KrawlがIPデータ、レピュテーション、地理位置情報のために呼び出すサードパーティAPI |
| [リバースプロキシ](https://github.com/blessedrebus/krawl/blob/main/docs/reverse-proxy.md) | NGINXの背後でKrawlをデプロイする方法、またはデコイサブドメインの使用方法 |
| [データベースバックアップ](https://github.com/blessedrebus/krawl/blob/main/docs/backups.md) | 自動データベースダンプジョブの有効化と設定 |
| [カナリアトークン](https://github.com/blessedrebus/krawl/blob/main/docs/canary-token.md) | canarytokens.orgを介した外部アラートトリガーの設定 |
| [ワードリスト](https://github.com/blessedrebus/krawl/blob/main/docs/wordlist.md) | 偽のユーザー名、パスワード、ディレクトリリストのカスタマイズ |
| [アーキテクチャ](https://github.com/blessedrebus/krawl/blob/main/docs/architecture.md) | コードベース、リクエストパイプライン、データベーススキーマ、バックグラウンドタスクの技術概要 |
| [Cloudflare Banlist同期](https://github.com/blessedrebus/krawl/blob/main/docs/cloudflare_banlist.md) | Krawlから禁止IPをCloudflareアカウントIPリストにプッシュし、WAFルールで使用します。同期はバックグラウンドタスクとして実行され、完全置換でリストを更新します。 |
| [ファイアウォールエクスポーター](https://github.com/blessedrebus/krawl/blob/main/docs/firewall-exporters.md) | REST APIを介してIP禁止リストをraw、iptables、またはnftables形式でエクスポートする |
| [ターピット](https://github.com/blessedrebus/krawl/blob/main/docs/tarpit.md) | 遅延とノイズパディングされた応答でAIクローラーを減速・妨害する |
| [メトリクスとモニタリング](https://github.com/blessedrebus/krawl/blob/main/docs/monitoring.md) | Prometheusメトリクスエンドポイント、公開メトリクスリファレンス、Grafanaダッシュボード、ServiceMonitorスクレイピング |

## 貢献

貢献を歓迎します！以下の手順に従ってください：
1. リポジトリをフォークする
2. フィーチャーブランチを作成する
3. 変更を加える
4. プルリクエストを送信する（変更内容を説明してください！）

## 免責事項
> [!CAUTION]
> これは偽装/ハニーポットシステムです。隔離された環境でデプロイし、セキュリティイベントを注意深く監視してください。適用される法律および規制に準拠して責任を持って使用してください。

## スター履歴
<img src="https://star-history.dera.page/svg?repos=BlessedRebuS/Krawl&amp;type=Date" width="600" alt="スター履歴チャート" />