> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# カスタム API スキャナーの仕様

> Dify がナレッジベースのアップロードファイルを検査する際に呼び出すスキャンサービスを構築します

> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](https://docs.dify.ai/en/self-host/use-dify/knowledge/file-security-scan-custom-endpoint.md) を参照してください。

**カスタム API** スキャナーでスキャンするナレッジベースでは、アップロードされたファイルを Dify が自社のスキャンサービスに送信します。その後、サービスが返した判定結果に従って処理します。問題のないファイルは通常どおりインデックス化され、感染したファイルはブロックされます。

エンドポイントが稼働したら、**連携** > **ファイルセキュリティスキャン** > **スキャナーを追加** > **カスタム API** で追加します。ナレッジベースでスキャンを有効にする方法は、[アップロードされたファイルのマルウェアスキャン](https://docs.dify.ai/ja/self-host/use-dify/knowledge/file-security-scan) を参照してください。

> [!NOTE]
>
> このスキャナーの種類は、**連携** の **カスタム API** セクションとは別のものです。同セクションは API ベースの拡張機能を管理するもので、リクエストの形式も異なります。

## ファイルの受信

Dify は、ファイルを 1 つずつ個別のリクエストで送信します。

```text theme={null}
POST <Endpoint URL>
Authorization: Bearer <API key>
Content-Type: multipart/form-data
```

任意の秘密の文字列を API キーとして決め、スキャナーの追加時に Dify に入力します。サービス側ではこのキーを検証し、一致しない場合は `401` を返してください。

フォームには、ファイルと 5 つのテキストフィールドが含まれます。

**file** `file`

スキャン対象のファイルです。

**scan\_id** `string`

このスキャンの ID です。Dify がスキャンを自動で再試行する際は、同じ ID が送信されます。そのため、同じリクエストが再び届いたときは、スキャンし直さずに初回の結果で応答できます。後からナレッジベースでドキュメントを再試行した場合は、新しい ID で新しいスキャンが始まります。

**file\_name** `string`

`report.docx` などのファイル名です。

**file\_size** `string`

バイト単位のファイルサイズを、`482113` のような 10 進数の文字列で表したものです。

**mime\_type** `string`

ファイルの MIME タイプです。Dify が判別できない場合は空になります。

**file\_hash** `string`

ファイル内容の SHA3-256 ハッシュを 16 進数で表したものです。空の場合もあります。常にハッシュが必要な場合は、サービス側でファイル内容から計算してください。

## 判定結果の返却

`2xx` のいずれかのステータスコードと、JSON オブジェクトを返します。

```json theme={null}
{
  "verdict": "infected",
  "threats": ["EICAR-Test-File"],
  "engine": "MyScanner 2.1"
}
```

**verdict** `string` *required*

`clean`、`infected`、`unscannable` のいずれかです。

**threats** `string[]`

検出された脅威の名前です。ブロックされたドキュメントのエラーメッセージでユーザーに表示されます。省略した場合、メッセージには `unknown` が検出されたと表示されます。

Dify は最大 20 件の名前を保持し、それぞれ 200 文字を超える部分は切り捨てます。

**engine** `string`

スキャンエンジンの名前またはバージョンです。Dify 上には表示されません。

**message** `string`

ファイルをスキャンできなかった理由です（最大 500 文字）。Dify 上には表示されません。

サービスが判定できないファイルの扱いは、ナレッジベースの **ファイルをスキャンできない場合（暗号化されている、またはサイズが大きすぎる）** で決まります。デフォルトではブロックされますが、スキャンせずに受け入れるよう設定することもできます。ブロックされたファイルに表示されるエラーメッセージは、返す内容によって次のように変わります。

* **サイズが大きすぎる場合**：`413` を返します。エラーメッセージには、ファイルがスキャナーのサイズ上限を超えていると表示されます。
* **暗号化されている、形式に対応していない、またはその他の理由の場合**：`unscannable` を返します。理由にかかわらず、エラーメッセージには、スキャナーがそのファイルに対応していないと表示されます。

## ステータスコードの選び方

Dify は、返されたステータスコードとボディに基づいて、ファイルの扱いを決めます。

| レスポンス | Dify の処理 |
| :- | :- |
| `2xx` と有効な `verdict` | 判定結果に従う |
| `401` または `403` | キーが無効とみなす。ナレッジベースの設定にかかわらずファイルをブロックし、再試行せず、スキャナーを **エラー** にする |
| `402` または `429` | クォータを使い切ったとみなし、`401` および `403` と同じように処理する |
| `413` | サイズ超過とみなし、ナレッジベースの **ファイルをスキャンできない場合（暗号化されている、またはサイズが大きすぎる）** の設定に従う |
| `5xx`、タイムアウト、または接続エラー | デフォルトで合計 3 回まで試行する（`FILE_SCAN_MAX_ATTEMPTS` で設定）。その後、ナレッジベースの **スキャナーが利用できない場合** の設定に従う |
| その他のステータス、リダイレクト、JSON ではないボディ、または不明な `verdict` | 解釈できない応答とみなす。再試行せず、ナレッジベースの **スキャナーが利用できない場合** の設定に従う |

> [!NOTE]
>
> 一時的な過負荷で、再試行すれば処理できる見込みがある場合は、`429` ではなく `503` を返してください。

## 制限時間内の応答

各リクエストには 2 分以内に応答してください。Docker Compose でデプロイしている場合、Dify のリクエストはプロキシを経由します。このプロキシは、2 分間応答がないリクエストを切断します。

このプロキシを経由しない場合は、Dify 自体のタイムアウトが上限になります。デフォルトは 300 秒で、`FILE_SCAN_REQUEST_TIMEOUT_SECONDS` で設定します。詳しくは [環境変数](https://docs.dify.ai/ja/self-host/deploy/configuration/environments.md#ファイルセキュリティスキャン) を参照してください。

タイムアウトしたリクエストは再送され、試行回数はデフォルトで最大 3 回です。そのため、エンドポイントの応答が遅いと、ドキュメントが約 6 分（3 × 2 分）待たされることがあります。その後、ナレッジベースの **スキャナーが利用できない場合** の設定が適用されます。

時間内に処理を終えられないとわかっている場合は、タイムアウトを待たずに、すぐに `413` または `unscannable` を返してください。

## Dify からエンドポイントへの接続

Dify の **エンドポイント URL** には、`http://scanner.example.internal:8000/scan` のように、パスを含む完全な URL を入力します。`localhost` ではなく、Dify から到達できるアドレスを使用してください。

Docker Compose でデプロイしている場合、Dify のリクエストが経由するプロキシは、デフォルトで内部アドレスへの通信もブロックします。エンドポイントが内部アドレスを使っている場合、そのアドレスを許可するまで、Dify はエンドポイントに接続できず、スキャナーも保存できません。許可するには、次のように設定します。

* **エンドポイント URL に IP アドレスを使う場合**：`SSRF_PROXY_ALLOW_PRIVATE_IPS` にそのアドレスを設定します。
* **エンドポイント URL にホスト名を使う場合**：`SSRF_PROXY_ALLOW_PRIVATE_DOMAINS` にそのホスト名を設定します。

詳しくは [環境変数](https://docs.dify.ai/ja/self-host/deploy/configuration/environments.md#ssrf-プロキシ) を参照してください。

プロキシは、`https` の通信をポート 443 でのみ許可します。デプロイ環境で `HTTP_REQUEST_NODE_SSL_VERIFY` が `false` に設定されていない限り、Dify は `https` エンドポイントの TLS 証明書を検証します。

## 保存前のテスト

エンドポイントが動作しているマシンから、Dify と同じ形式のリクエストを送信します。

```bash theme={null}
curl http://localhost:8000/scan \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@report.docx" \
  -F "scan_id=test-1" \
  -F "file_name=report.docx" \
  -F "file_size=482113" \
  -F "mime_type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -F "file_hash="
```

スキャンロジックを実装したら、このリクエストを 2 回送信します。1 回目は問題のないファイル、2 回目は EICAR テストファイルを使い、それぞれに合わせて `file_name`、`file_size`、`mime_type` を変更します。エンドポイントからは、1 回目に `clean`、2 回目に `infected` が返るはずです。

> [!NOTE]
>
> EICAR テストファイルは無害なファイルですが、どのウイルス対策エンジンもマルウェアとして検出します。[eicar.org](https://www.eicar.org) から入手できます。

ナレッジベースでスキャナーを使い始める前に、実際のファイルもいくつか送信して、誤検知がないか確認してください。

Dify は判定結果を保持します。ワークスペース内で同じ内容を同じスキャナーで再度チェックする場合は、エンドポイントを呼び出さずに以前の判定結果を再利用します。

* **`infected`**：無期限に再利用されます。そのため、問題のないファイルをサービスが誤って検出した場合、スキャナーを修正した後もそのファイルはブロックされたままです。
* **`clean`**：デフォルトで 24 時間再利用されます（`FILE_SCAN_CLEAN_VERDICT_TTL_HOURS` で設定）。その間は、スキャナーを更新して検出できるようにしても、同じファイルはそのまま通過します。

Dify は、スキャナーの保存時と **テスト** のクリック時に、次のファイルを 1 つ送信して接続を確認します。

* `file`：`clean-test.txt`（`text/plain`）
* `scan_id`：`connectivity-check`
* `file_hash`：空

形式が正しい判定結果であれば、内容にかかわらず確認に合格します。`413` も合格です。Dify がスキャナーを保存するのは、確認に合格した場合だけです。

ナレッジベースでスキャナーを使い始めたら、そのナレッジベースに [EICAR テストファイルをアップロード](https://docs.dify.ai/ja/self-host/use-dify/knowledge/file-security-scan#スキャンの動作確認) して、一連の処理全体を確認してください。

## サンプルを基にした実装

次の Flask エンドポイントの `my_scanner` を、独自のスキャンロジックに置き換えてください。

```python scanner.py theme={null}
import hmac
import os

from flask import Flask, jsonify, request

app = Flask(__name__)
API_KEY = os.environ["SCANNER_API_KEY"]  # the API key you enter in Dify


def my_scanner(content: bytes) -> list[str]:
    """Replace with your scanning logic: return the names of any threats found."""
    return []


@app.post("/scan")
def scan():
    expected = f"Bearer {API_KEY}"
    received = request.headers.get("Authorization", "")
    if not hmac.compare_digest(received.encode(), expected.encode()):
        return jsonify(error="invalid API key"), 401

    content = request.files["file"].read()
    threats = my_scanner(content)
    if threats:
        return jsonify(verdict="infected", threats=threats, engine="MyScanner")
    return jsonify(verdict="clean", engine="MyScanner")
```

コードを `scanner.py` として保存します。次に Flask をインストールし、Dify に入力する API キーを指定してエンドポイントを起動します。

```bash theme={null}
pip install flask
SCANNER_API_KEY=your-api-key flask --app scanner run --host 0.0.0.0 --port 8000
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.