Skip to content

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 / MaxConnectionQueueLength must be tuned server-side (ops note, no client pool in v1).
  • Neutral / follow-ups: Add MPL-2.0.txt to LICENSES/ and a REUSE.toml entry for the clamd dep. storage.scan.max_size should be set to match the daemon's StreamMaxLength. Integration suite is gated behind the integration build tag (real clamav/clamav:1.5_base-debian container) so the fast local gate stays cheap; renovate should track the v1.0.1 tag.

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.