ADR-0011: baruwa-enterprise/clamd for upload malware scanning, fail-closed by default¶
- Status: Accepted
- Date: 2026-06-19
- Deciders: @lusoris
- Tags: security, storage, supply-chain
Context¶
Apps accept untrusted file uploads; the framework needs to scan those bytes for malware before they are stored or served. This is a trust-boundary control (per principles §2.2 SEI CERT input-validation and §2.5 OWASP ASVS L2), so two properties are non-negotiable: (1) the scanner must report which signature fired, not just a boolean, for incident response and audit; and (2) a scanner outage must not silently let unscanned bytes through. ClamAV's clamd daemon is the de-facto open-source AV engine and speaks a simple INSTREAM wire protocol over TCP / unix socket. We need a Go client that gives a structured verdict and propagates context.Context.
Decision¶
We will use github.com/baruwa-enterprise/clamd (pinned v1.0.1) as the clamd client, wrapped by a new storage/scan fx module exposing a Scanner interface (Scan / ScanStrict / Ping) that maps clamd's structured Response to a typed Verdict. The default backend is clamd and the default policy is fail-closed: an unreachable daemon fails fx startup (bounded boot-time Ping) unless fail_open: true is set explicitly. A noop (always-clean) backend exists for dev/test but is opt-in only and logs a loud WARN on construction so it can never silently disable scanning in production. The module does not mutate storage.Bucket; callers compose scan-before-Put.
Alternatives considered¶
| Option | Pros | Cons | Why not chosen |
|---|---|---|---|
baruwa-enterprise/clamd |
Structured Response{Filename,Signature,Status,Raw}; ctx-first on every method; ~zero-dep (stdlib + INSTREAM framing handled); most recently maintained |
MPL-2.0 file-level copyleft | Chosen — only lib giving the signature name + ctx propagation the trust boundary requires. |
lyimmi/go-clamd |
MIT, zero deps | ScanStream returns only (bool, error) — no signature |
Boolean-only verdict is a dealbreaker for audit/IR. |
dutchcoders/go-clamd |
The original | Unmaintained; channel-based API, no context.Context |
Fails the maintained + ctx-propagation conventions. |
| Hand-rolled INSTREAM client | Total control, no dep | 4-byte BE chunk framing + StreamMaxLength handling is a parsing-bug surface in the trust boundary | Reserve only as break-glass if the dep is dropped. |
lescactus/clamav-api-go |
REST wrapper | A second deployable + an HTTP hop for no benefit over speaking clamd directly | Wrong shape (service, not library). |
Consequences¶
- Positive: Verdicts carry the real signature name (e.g.
Eicar-Test-Signature) for audit logging. Fail-closed default + opt-in-with-WARN noop means a misconfigured or down scanner is loud, never silent. Dial-per-command keeps the client concurrency-safe with no shared mutable state. - Negative: MPL-2.0 (file-level copyleft) enters the dependency graph — safe as an unmodified import, but must be recorded in REUSE.toml / LICENSES and baruwa's source must never be edited in-tree (any patch goes in a separate adapter file). Dial-per-command means N concurrent uploads = N clamd connections; clamd
MaxThreads/MaxConnectionQueueLengthmust be tuned server-side (ops note, no client pool in v1). - Neutral / follow-ups: Add
MPL-2.0.txttoLICENSES/and a REUSE.toml entry for the clamd dep.storage.scan.max_sizeshould be set to match the daemon'sStreamMaxLength. Integration suite is gated behind theintegrationbuild tag (realclamav/clamav:1.5_base-debiancontainer) so the fast local gate stays cheap; renovate should track thev1.0.1tag.
References¶
- baruwa-enterprise/clamd pinned at
v1.0.1. storage/scan/AGENTS.md— API + config + security posture.- EICAR is the standard, safe AV test vector — used in tests; no real malware in-tree.