## クイックスタート

### 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/HEAD/docker/) ディレクトリにもあります。**開発**（ソースからのビルド、ホットリロード付き）には、[`docker/dev/`](https://github.com/blessedrebus/krawl/blob/HEAD/docker/dev/) の compose ファイルを使用してください。

両モードの詳細は、[Deployment Modes](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deployment-modes.md) を参照してください。

### Kubernetes
**Krawl は Kubernetes 上でもネイティブに利用できます**。インストールは [マニフェスト経由](https://github.com/blessedrebus/krawl/blob/HEAD/kubernetes/README.md) または [Helm チャートを使用](https://github.com/blessedrebus/krawl/blob/HEAD/helm/README.md) のいずれかで行えます。

Helm チャートは、**スケーラブルモードがデフォルト**で、PostgreSQL と Redis がバンドルされています:```bash
helm install krawl oci://ghcr.io/blessedrebus/krawl-chart --version 2.3.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

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

## 設定
Krawl は **構成階層** を使用しており、**環境変数は設定ファイルよりも優先されます**。このアプローチは、Docker デプロイや導入直後の簡単なカスタマイズに推奨されます。

### config.yaml による設定
高度な設定（Docker Compose や Helm chart デプロイなど）には [config.yaml](https://github.com/blessedrebus/krawl/blob/HEAD/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` | 1 ページあたりのリンク数（`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 | Loopback, RFC1918, link-local, CGNAT |
| `KRAWL_BANLIST_EXPORT_PATH` | 公開バンリストのダウンロードパス（例: `/public_banlist.txt`）（空 = 無効） | `""` |
| `KRAWL_BANLIST_SOURCES` | 取得してマージするカンマ区切りのアップストリームバンリスト URL | Krawl community banlist |
| `KRAWL_BANLIST_REFRESH_INTERVAL` | アップストリームバンリスト取得間隔（秒） | `3600` |

</details>

<details>
<summary><b>AI 生成の偽装ページ</b>（10 変数）</summary>

[AI 生成ドキュメント](https://github.com/blessedrebus/krawl/blob/HEAD/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/HEAD/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/HEAD/docs/ai_generation.md)を参照してください。

また、PRを開いて**デセプションテンプレートを提供**することもできます。[デセプションテンプレートの提供](https://github.com/blessedrebus/krawl/blob/HEAD/docs/deception_pages.md#contributing-deception-templates-via-pr)を参照してください。

## リバースプロキシまたはCDNの背後での実行

**NGINX、Traefik、CloudFlareなどのプロキシ**では、Krawlが実際のIPを確認できるようにヘッダー転送が必要です。設定例と完全なヘッダーリストについては、[リバースプロキシドキュメント](https://github.com/blessedrebus/krawl/blob/HEAD/docs/reverse-proxy.md)を参照してください。

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

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

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

## 追加ドキュメント

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