Overview
Attachments, avatars, documents, imports: anything a user uploads is content you did not write, arriving inside a request your application is about to trust.
Content scanning hands the request body to ClamAV before it is forwarded upstream. A signature hit refuses the request with 403, so infected content never reaches your storage, your queue or a downstream worker. It is proxy-mode only: something has to hold the decrypted body.
When you see this
- Your service accepts uploads of any kind.
- Uploaded files are stored, processed by a worker or shown to other users.
Steps
- 01
Arm the scanner
Enabling the scanner on its own scans nothing. This arms it and sets what happens to an upload it cannot inspect.
/etc/synapse/config.yaml proxy: content_scanning: enabled: true clamav_server: "localhost:3310" max_file_size: 10485760 unscannable: block - 02
Aim it at the upload paths
A WAF rule with the content_scanning action selects the traffic. Everything outside it is untouched and costs nothing; scanning every body would put a ClamAV round trip in front of every API write.
WAF rule, action content_scanning starts_with(http.request.path, "/upload")DecisionDoes the agent log "content scanning is enabled but no WAF rule uses the content_scanning action"?Yes Nothing is being scanned. Add the rule above, or fix the one that should match.
No The rule is in place. Test it.
- 03
Decide what happens to files you cannot scan
An upload can be selected and still be uninspectable: over max_file_size, or chunked past it. block refuses it with 413; pass forwards it unscanned and logs it. Choosing pass is legitimate, but make it deliberately.
- 04
Test with the EICAR file
Upload the standard EICAR antivirus test file to a selected path and expect a 403. Upload the same file to a path the rule does not select and expect it to pass: that is the boundary of your coverage.
- 05
Alert on scan failures
If ClamAV is unreachable the request proceeds and the failure is logged. A quietly dead scanner looks identical to a clean one, so watch for the failures, and keep the signature database current.
Common mistakes
- Enabling the scanner without a content_scanning rule: it inspects nothing.
- Setting unscannable to pass without meaning to, which quietly turns a scanned endpoint into a partially scanned one.
- Adding a second upload endpoint later without extending the rule to cover it.
Escalate when
- A signature hit on a file that reached storage before scanning was in place.
Where this stops working
- ClamAV is signature-based: it catches known malware, not a payload written for you.
- Latency scales with body size, plus a round trip, on the selected traffic.