This scanner type is separate from the Custom Endpoint section of Integrations, which holds API-based extensions with a different request format.
Receive the File
Dify sends each file in its own request:401.
The form carries the file and five text fields:
An ID for this scan. Dify’s automatic retries of a scan send the same ID, so you can answer a repeated request from the first scan instead of scanning again. Retrying the document in the knowledge base later starts a new scan with a new ID.
The SHA3-256 hash of the file content, in hex. It can be empty. If your service needs a hash every time, compute one from the content.
Return a Verdict
Answer with any2xx status and a JSON object:
Names of the threats found, shown to users in the blocked document’s error message. Without them, the message says
unknown was detected.Dify keeps up to 20 names, each cut to 200 characters.Why your service couldn’t scan the file, up to 500 characters. Dify doesn’t show it in the product.
- Too large: return
413. The error message says the file exceeds the scanner’s size limit. - Encrypted, an unsupported format, or any other reason: return
unscannable. The error message says the scanner doesn’t support the file, whatever your reason was.
Choose the Right Status Code
Dify decides what to do with the file from your status code and body.For a brief overload that a retry would get past, return
503, not 429.Answer Within the Timeout
Answer each request within 2 minutes. In a Docker Compose deployment, Dify’s requests pass through a proxy that closes a request after 2 minutes without a response. Without that proxy, the limit is Dify’s own timeout: 300 seconds by default, set byFILE_SCAN_REQUEST_TIMEOUT_SECONDS. See Environment Variables for details.
A request that runs out of time is sent again, up to 3 attempts by default. So a slow endpoint can keep a document waiting about 6 minutes (3 × 2 minutes) before the knowledge base’s When the scanner is unavailable choice applies.
When your service knows it can’t finish a file in time, answer at once with 413 or unscannable instead of letting the request time out.
Make the Endpoint Reachable
In Dify, enter your endpoint’s full URL as the Endpoint URL, path included, such ashttp://scanner.example.internal:8000/scan. Use an address Dify can reach, not localhost.
In a Docker Compose deployment, the proxy that Dify’s requests pass through also blocks internal addresses by default. If your endpoint has one, Dify can’t reach it or save the scanner until you allow the address:
- If the Endpoint URL uses an IP address: set
SSRF_PROXY_ALLOW_PRIVATE_IPSto that address. - If the Endpoint URL uses a hostname: set
SSRF_PROXY_ALLOW_PRIVATE_DOMAINSto that hostname.
https, the proxy allows only port 443. Dify verifies an https endpoint’s TLS certificate unless the deployment sets HTTP_REQUEST_NODE_SSL_VERIFY to false.
Test Before You Save
Send your endpoint a request shaped like Dify’s, from the machine it runs on:file_name, file_size, and mime_type to match each. Your endpoint should answer clean for the first and infected for the second.
The EICAR test file is a harmless file that every antivirus engine reports as malware, available from eicar.org.
infected: reused for good, so a clean file your service wrongly flags stays blocked even after you fix the scanner.clean: reused for 24 hours by default, set byFILE_SCAN_CLEAN_VERDICT_TTL_HOURS. During that time, the same file passes even if you’ve updated the scanner to catch it.
file:clean-test.txt, astext/plainscan_id:connectivity-checkfile_hash: empty
413. Dify saves the scanner only when the check passes.
Once a knowledge base uses the scanner, upload the EICAR test file there to check the whole path.
Start from an Example
Replacemy_scanner in this Flask endpoint with your own scanning logic:
scanner.py
scanner.py, then install Flask and start the endpoint with the API key you’ll enter in Dify: