Expand description
§mailrs-clamav
Async ClamAV (clamd) TCP client. Implements the zINSTREAM malware
scanning protocol plus PING / VERSION daemon commands. Tokio-based,
no external state.
§Quickstart
use mailrs_clamav::{scan, ClamavResult};
match scan("127.0.0.1:3310", data).await {
ClamavResult::Clean => {
// accept the message
}
ClamavResult::Virus(name) => {
eprintln!("rejected: virus={name}");
// reject 5xx — DO NOT silently drop, the sender needs the bounce
}
ClamavResult::Error(e) => {
eprintln!("clamd unreachable: {e}");
// fail-open or fail-closed is a policy choice — handle here
}
}§What this crate does
scan(addr, data)—zINSTREAMscan with 30s default timeoutscan_with_timeout(addr, data, timeout)— same with custom timeoutping(addr, timeout) -> bool—zPING→PONGhealth checkversion(addr, timeout) -> Option<String>—zVERSIONfor ops dashboardsparse_response(bytes)— exposed for testing / reusing the reply parser without going through the socket
§Wire protocol
client → clamd: zINSTREAM\0
client → clamd: [u32 BE: chunk_len][chunk_bytes...] (repeat)
client → clamd: [u32 BE: 0] (terminator)
clamd → client: stream: OK\0 (clean)
clamd → client: stream: <virus-name> FOUND\0 (detection)
clamd → client: <error text> ERROR\0 (error)Chunks are capped at CHUNK_SIZE (2 MiB). For very large attachments,
verify your clamd.conf StreamMaxLength setting (default 25 MB).
§What this crate does not
- No connection pool / re-use. Each
scanopens a fresh TCP connection. ClamAV is typically deployed alongside the mail server on localhost; the connect overhead is negligible vs. the scan itself. Pooling could be added in a future minor without breaking compat. - No Unix domain socket. TCP only.
clamdsupports both; this crate covers the TCP form. If you need UDS, file an issue. - No
MULTISCAN/CONTSCAN/STATS/RELOAD. Only the three commands listed above. The full clamd command set is large and most are admin-only; this crate covers the per-message data path. - No SCAN-with-path.
INSTREAMonly (the daemon never reads files from the filesystem; the bytes go over the socket). This is the safe shape for sandboxed deployments whereclamddoesn’t share a filesystem with the mail server.
§Performance
Measured (criterion, M-series Mac, release, 100-sample median):
| Operation | Median |
|---|---|
parse_response (clean reply) | ~9 ns |
parse_response (virus, short name) | ~60 ns |
parse_response (virus, long name) | ~78 ns |
parse_response (error reply) | ~49 ns |
parse_response (empty input) | ~21 ns |
scan itself is network-bound — the bench numbers above are the CPU
pieces. A localhost clamd scan of a 100 KB payload typically completes
in 10-30 ms; the CPU portion of that is microseconds.
Reproduce: cargo bench -p mailrs-clamav --bench clamav. Workspace
PERFORMANCE.md carries the same table.
§Stone audit (v3 cycle, 2026-05-25)
| Axis | Status |
|---|---|
| doc | ✅ clean (cargo doc --no-deps -p mailrs-clamav) |
| test | line cov: 71.2% (cargo llvm-cov -p mailrs-clamav --summary-only) |
| bench | ✅ 1 file(s) criterion + ✅ 3 gate(s) perf_gate.rs |
| size | release rlib: 88 KB |
| fuzz | ❌ none |
| mem | dhat profile pending (v3.4 backlog) |
§Competitor comparisons
- Searched crates.io + competing impls: see PERFORMANCE.md or ‘first-in-Rust’ marker.
§License
Apache-2.0 OR MIT.
Enums§
- Clamav
Result - Outcome of a ClamAV scan.
Constants§
- CHUNK_
SIZE - Max chunk size per ClamAV INSTREAM frame.
- DEFAULT_
TIMEOUT - Default per-call timeout. Applied to connect + write + read together. ClamAV scans of typical 100 KB mails finish in <100 ms; large attachments (5-10 MB) can take seconds. Pick something that won’t stall your inbound pipeline.
Functions§
- parse_
response - Parse a
clamdINSTREAM reply. - ping
- PING the daemon. Returns
trueifclamdis up and repliesPONGwithin the timeout. - scan
- Scan
dataagainst aclamddaemon listening ataddr(e.g."127.0.0.1:3310") using the zINSTREAM protocol variant. - scan_
with_ timeout - Like
scanbut with a caller-supplied timeout. - version
- Ask
clamdfor its version string. Useful for ops dashboards.