Skip to main content
With a Custom Endpoint scanner, Dify sends your scanning service the files uploaded to a knowledge base that scans with it. Dify then acts on the verdict your service returns: a clean file is indexed as usual, and an infected one is blocked. Once your endpoint is running, add it in Integrations > File Security Scan > Add scanner > Custom Endpoint. See Scan Uploaded Files for Malware for turning on scanning in a knowledge base.
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:
Make up a secret string as the API key, enter it in Dify when you add the scanner, and have your service check it. When the key doesn’t match, return 401. The form carries the file and five text fields:
file
The file to scan.
string
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.
string
The file’s name, such as report.docx.
string
The file’s size in bytes, as a decimal string, such as 482113.
string
The file’s MIME type, or empty when Dify doesn’t know it.
string
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 any 2xx status and a JSON object:
string
required
clean, infected, or unscannable.
string[]
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.
string
Your engine’s name or version. Dify doesn’t show it in the product.
string
Why your service couldn’t scan the file, up to 500 characters. Dify doesn’t show it in the product.
When your service can’t judge a file, the knowledge base’s When a file cannot be scanned (encrypted or too large) choice decides whether it’s blocked (the default) or let in unscanned. What you return sets the error message users see on a blocked file:
  • 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 by FILE_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 as http://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_IPS to that address.
  • If the Endpoint URL uses a hostname: set SSRF_PROXY_ALLOW_PRIVATE_DOMAINS to that hostname.
See Environment Variables for details. For 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:
Once your scanning logic is in place, send this request twice: once with a clean file and once with the EICAR test file, updating 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.
Also send a sample of your real files, to catch false alarms before a knowledge base uses your scanner. Dify remembers verdicts. When the same content is checked again in the workspace by the same scanner, Dify reuses the earlier verdict instead of calling your endpoint:
  • 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 by FILE_SCAN_CLEAN_VERDICT_TTL_HOURS. During that time, the same file passes even if you’ve updated the scanner to catch it.
When you save the scanner, and whenever you click Test, Dify checks the connection by sending one file:
  • file: clean-test.txt, as text/plain
  • scan_id: connectivity-check
  • file_hash: empty
Any well-formed verdict passes, and so does 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

Replace my_scanner in this Flask endpoint with your own scanning logic:
scanner.py
Save the code as scanner.py, then install Flask and start the endpoint with the API key you’ll enter in Dify:
Last modified on November 18, 2026